Skip to content

deployment_guide.md

Latest commit

 

History

History
367 lines (243 loc) · 10.1 KB

deployment_guide.md

File metadata and controls

367 lines (243 loc) · 10.1 KB
Raw

Deployment Guide — BugReplay

This guide will walk you through deploying your BugReplay to production. Since you're new to web development, I've included detailed explanations for each step.

Prerequisites

Before you start, you'll need:

  1. A Cloudflare account (free tier is sufficient)

  2. Node.js installed (version 18 or higher)

  3. Wrangler CLI (Cloudflare's deployment tool)

    • Install with: npm install -g wrangler
    • Verify installation: wrangler --version

Step 1: Authenticate with Cloudflare

Open your terminal and run:

wrangler login

This will open your browser. Click "Allow" to authorize Wrangler to access your Cloudflare account.

Step 2: Create Cloudflare Resources

2a. Create R2 Bucket (for storing videos and telemetry)

R2 is Cloudflare's object storage (similar to AWS S3, but with free egress).

wrangler r2 bucket create bugreplay-storage

You should see:

✅ Successfully created bucket 'bugreplay-storage'.

2b. Create D1 Database (for storing session metadata)

D1 is Cloudflare's SQL database.

wrangler d1 create bugreplay-db

Copy the database_id from the output. It will look like:

✅ Successfully created DB 'bugreplay-db'

database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Important: Save this database_id — you'll need it in the next step.

Step 3: Update wrangler.toml Configuration

Open worker/wrangler.toml and update the following values:

name = "bugreplay-worker"
main = "src/index.js"
compatibility_date = "2024-01-01"

[vars]
SITE_URL = "https://your-worker-url.workers.dev"  # You'll get this after first deploy
R2_PUBLIC_URL = "https://pub-xxxxxxxxxxxxx.r2.dev"  # You'll get this after setting up R2

# JWT_SECRET is set via wrangler secret (not stored in this file):
# wrangler secret put JWT_SECRET

# AUTH_PASSWORD is set via wrangler secret (not stored in this file):
# wrangler secret put AUTH_PASSWORD

[[r2_buckets]]
binding = "BUCKET"
bucket_name = "bugreplay-storage"

[[d1_databases]]
binding = "DB"
database_name = "bugreplay-db"
database_id = "your-database-id-here"  # Replace with the ID from Step 2b

What to update:

  1. database_id: Paste the ID you copied from Step 2b
  2. SITE_URL: Leave as placeholder for now — you'll update after first deployment
  3. R2_PUBLIC_URL: Leave as placeholder for now — you'll set this up later

Step 4: Set Up Secrets

Secrets are sensitive values that are encrypted and never stored in your code.

4a. Set the AUTH_PASSWORD secret

This is the password you'll use to login and upload recordings.

wrangler secret put AUTH_PASSWORD

When prompted, enter your desired password (you won't see it as you type). Press Enter to confirm.

Choose a strong password — this protects your upload endpoint.

4b. Set the JWT_SECRET secret

This is used to sign and verify authentication tokens.

wrangler secret put JWT_SECRET

When prompted, enter a random string. You can generate one with:

# On Windows (PowerShell):
-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) })

# On Mac/Linux:
openssl rand -base64 32

Copy the output and paste it when prompted.

Step 5: Initialize the Database

The migration file already exists at worker/migrations/0001_create_sessions.sql. It creates the sessions table with columns for id, video_key, telem_key, created_at, browser, os, viewport, and url, plus an index on created_at.

Apply the migration to your database:

wrangler d1 migrations apply bugreplay-db --remote

You should see:

🌀 Executing on bugreplay-db (your-database-id-here):
✅ Successfully applied 1 migration

Step 6: Deploy the Worker

Navigate to the worker directory and deploy:

cd worker
npm install
wrangler deploy

You'll see output like:

✅ Successfully published your Worker to
  https://bugreplay-worker-your-subdomain.workers.dev

Copy this URL — this is your SITE_URL.

Update wrangler.toml:

SITE_URL = "https://bugreplay-worker-your-subdomain.workers.dev"

Step 7: Set Up R2 Public Access

To make video files publicly accessible (so viewers can watch them), you need to enable R2 public access.

7a. Create a Custom Domain for R2 (Optional but Recommended)

For a production setup, you can use a custom domain. For testing, Cloudflare provides a default public URL.

Check your R2 bucket settings in the Cloudflare dashboard:

  1. Go to https://dash.cloudflare.com
  2. Navigate to: R2 → Buckets → bugreplay-storage → Settings
  3. Look for "Public Access" and enable it if not already enabled
  4. Note the public URL pattern

Update wrangler.toml:

R2_PUBLIC_URL = "https://pub-xxxxxxxxxxxxx.r2.dev"

Step 8: Test the Backend Deployment

Before loading the extension, verify your worker is running:

# Test the root endpoint (should return 404 or serve viewer)
curl https://bugreplay-worker-your-subdomain.workers.dev

# Test the login endpoint
curl -X POST https://bugreplay-worker-your-subdomain.workers.dev/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"password":"your-password-here"}'

If successful, you'll get a JWT token in response:

{"token":"eyJhbGciOiJIUzI1NiIs..."}

Step 9: Load the Browser Extension

9a. Install the Extension Locally

  1. Open Chrome or Edge
  2. Navigate to: chrome://extensions/ (or edge://extensions/)
  3. Enable Developer mode (toggle in top-right)
  4. Click Load unpacked
  5. Select the extension folder from your project

The extension icon should now appear in your browser toolbar.

9b: Configure the Extension Backend URL

The extension needs to know where your worker is deployed.

Create extension/background/config.local.js (this file is gitignored — never commit your real URL) with your worker URL:

self.BACKEND_URL = "https://YOUR-WORKER.workers.dev";

service-worker.js loads this via importScripts('config.local.js') and falls back to a placeholder if missing.

Reload the extension:

  1. Go to chrome://extensions/
  2. Click the refresh icon on your extension card

Step 10: Test End-to-End

  1. Click the extension icon in your toolbar
  2. Get a JWT token — send a POST request to your login endpoint: 
    curl -X POST https://bugreplay-worker-your-subdomain.workers.dev/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"password":"your-password-here"}'
    Copy the token value from the response.
  3. Click the settings gear icon (⚙️) in the extension popup
  4. Paste your JWT token into the JWT Token field and click "Save"
  5. Click "Start Recording" — the extension will begin capturing your screen
  6. Interact with your browser — visit some pages, click around
  7. Click "Stop Recording" — the extension will upload to your worker
  8. Copy the viewer URL that appears (it's automatically copied to clipboard)
  9. Open the viewer URL in a new tab — you should see the video with synced telemetry

Step 11: Production Checklist

Before sharing your deployment:

  • Verify secrets are set — run wrangler secret list to confirm JWT_SECRET and AUTH_PASSWORD exist
  • Set up a custom domain (optional, but recommended for production)
  • Enable Cloudflare Access (optional, for additional protection)
  • Configure rate limiting in Cloudflare dashboard (prevents abuse)
  • Set up monitoring with Cloudflare Analytics
  • Test upload size limits — Workers have a 100MB request limit by default

Troubleshooting

Error: "Invalid JWT"

  • Run wrangler secret list to verify JWT_SECRET is set
  • If missing, set it with: wrangler secret put JWT_SECRET

Error: "Database not found"

  • Verify database_id in wrangler.toml matches your D1 database
  • Run wrangler d1 list to see your databases

Error: "R2 bucket not found"

  • Verify the bucket name in wrangler.toml is bugreplay-storage
  • Run wrangler r2 bucket list to see your buckets

Extension can't connect to worker

  • Check browser console (F12) for CORS errors
  • Verify BACKEND_URL in extension/background/service-worker.js matches your worker URL
  • Make sure your worker is deployed: wrangler deployments list

Video won't play in viewer

  • Verify R2 public access is enabled in Cloudflare dashboard
  • Check that R2_PUBLIC_URL in wrangler.toml is correct
  • Open browser Network tab (F12) to see if video URLs are accessible

Cost Estimate (Cloudflare Free Tier)

Good news — Cloudflare's free tier is generous:

Resource Free Limit Expected Usage
Workers Requests 100,000/day < 100/day (personal use)
Workers CPU Time 10ms/day avg < 1s/day (personal use)
R2 Storage 10 GB < 1 GB (personal use)
R2 Class A Operations 1M/month < 1K/month
R2 Class B Operations 10M/month < 10K/month
D1 Database 5 GB stored < 1 MB (personal use)
D1 Rows Read 5M/day < 100/day

You likely won't exceed free limits for personal use.

Next Steps

After your initial deployment:

  1. Customize the viewer UI — Edit the embedded HTML/CSS/JS in worker/src/index.js (VIEWER_HTML, VIEWER_CSS, VIEWER_JS constants)
  2. Add your branding — Update icons and colors
  3. Set up monitoring — Enable Cloudflare Web Analytics
  4. Configure custom domain — Use your own domain instead of *.workers.dev
  5. Share with others — Send viewer links to test the public replay feature

Need Help?

You're done! 🎉 Your BugReplay is now deployed and ready to record and share browser sessions.