Deploy to Cloudflare Workers

The Worker handles the collector endpoint, the dashboard API and sign-in. The dashboard pages, the recorder script and the demo shop are served as static assets from the same Worker.

You need a Cloudflare account, Node 24 or later, and an S3-compatible bucket. The Workers paid plan is recommended: the free plan allows 10 ms of CPU per request, which decompressing a large first snapshot or checking a password (PBKDF2 with 100,000 iterations) can exceed.

1. Get the code

git clone https://github.com/replayowl/replayowl
cd replayowl
npm install

2. Create a bucket and an access key

Create a bucket and an access key that can only read and write that bucket. For Cloudflare R2, the endpoint is https://<account-id>.r2.cloudflarestorage.com and the region is auto.

3. Point the Worker at the bucket

Edit vars in wrangler.jsonc:

4. Create the database

Use D1 or an existing Postgres. For D1:

npx wrangler d1 create replayowl

Add the d1_databases block it prints to wrangler.jsonc, with the binding name DB.

For Postgres, create a Hyperdrive configuration and add the hyperdrive block it prints, with the binding name HYPERDRIVE:

npx wrangler hyperdrive create replayowl --connection-string="postgres://user:password@host:5432/replayowl"

If both are configured, the Worker uses D1. If neither is, every request returns a 500 error that names the missing setting. Tables are created on the first request.

5. Store the secrets

npx wrangler secret put S3_ACCESS_KEY_ID
npx wrangler secret put S3_SECRET_ACCESS_KEY
npx wrangler secret put SETUP_TOKEN

SETUP_TOKEN is optional but recommended. Until the admin password is set, anyone who opens the dashboard could set it; with a setup token, they also need the token.

6. Deploy

npm run deploy

Open the Worker’s URL, set the admin password, and you will see an empty session list. Then add the recorder to your site.

Debugging locally on workerd

Copy .dev.vars.example to .dev.vars, fill in the secrets, and run:

npm run dev:worker