Quick start on Cloudflare
The Cloudflare edition runs on Workers, Durable Objects, D1 and R2 in your own account. It needs the Workers Paid plan: email sign-in codes need it, and it lifts the Free plan’s CPU, subrequest and D1 query limits. To try The Runbook without it, use the Docker quick start.
Run every command from cloudflare/ in a checkout, with that directory’s
wrangler (npx wrangler).
1. Create the resources
Section titled “1. Create the resources”npx wrangler d1 create runbook-productionnpx wrangler r2 bucket create runbook-blobsnpx wrangler r2 bucket create runbook-user-contentnpx wrangler queues create runbook-notificationsnpx wrangler queues create runbook-notifications-dlq2. Write the two configs
Section titled “2. Write the two configs”Copy wrangler.jsonc.example to wrangler.prod.jsonc and
wrangler.auth.jsonc.example to wrangler.auth.prod.jsonc; both are
git-ignored. Fill in the D1 ID, the bucket and queue names, and the origins:
- the api Worker’s origin variable is
ORIGIN, the auth Worker’s isRUNBOOK_ORIGIN; set both to the same app origin; - set
RUNBOOK_USERCONTENT_ORIGINon the api Worker to a different hostname, preferably on a separate registrable domain; - uncomment the api config’s
AUTHservice andassetsblocks.
3. Build
Section titled “3. Build”node scripts/build-worker.mjs worker(cd ../auth && node scripts/build.mjs)(cd ../web && node scripts/build-wasm.mjs && npm run build)node scripts/prepare-assets.mjs4. Apply the D1 migrations before traffic
Section titled “4. Apply the D1 migrations before traffic”npx wrangler d1 migrations apply DB --remote -c wrangler.prod.jsoncnpx wrangler d1 migrations apply DB --remote -c wrangler.auth.prod.jsonc5. Deploy
Section titled “5. Deploy”The two Workers bind each other, and a service binding to a Worker that doesn’t exist yet fails the deploy. The first time, deploy in this order:
- the auth Worker without its
servicesblock (comment it out once); - the api Worker:
npx wrangler deploy -c wrangler.prod.jsonc; - the auth Worker again, with
servicesrestored:npx wrangler deploy -c wrangler.auth.prod.jsonc.
6. Set the secrets
Section titled “6. Set the secrets”Use npx wrangler secret put NAME -c <config>, piping each value in from a
file outside the repository:
- api Worker:
BOOTSTRAP_SECRET,WEBHOOK_SECRET_KEY,RUNBOOK_UPLOAD_SIGNING_KEYandRUNBOOK_AUTH_INTERNAL_SECRET; - auth Worker:
RUNBOOK_AUTH_SECRETand the sameRUNBOOK_AUTH_INTERNAL_SECRET.
7. Attach the hostnames
Section titled “7. Attach the hostnames”Attach the app origin and the user-content origin as Workers custom domains of the api Worker. Check the zone first: a wildcard DNS record already answers for every subdomain, and a custom domain takes that name over.
8. Create the first owner
Section titled “8. Create the first owner”Send the bootstrap secret in the x-bootstrap-secret header:
curl -X POST https://runbooks.example.com/internal/bootstrap \ -H "x-bootstrap-secret: $BOOTSTRAP_SECRET" \ -H "Content-Type: application/json" \ -d '{"organization": "My Organization", "user_name": "Initial Admin", "project_slug": "default", "owner_email": "admin@example.com"}'The 201 response carries the organization, user and project IDs and a
personal and a service token, shown once. A second call returns 409
(bootstrap.already_initialized). Then remove the secret, which disables
the route:
npx wrangler secret delete BOOTSTRAP_SECRETUpdating
Section titled “Updating”npm run update (from cloudflare/) backs up D1 with a Time Travel
bookmark, applies migrations, deploys both Workers, verifies /v1/meta and
rolls back the Workers on failure. Start with npm run update -- --dry-run.
Until a release is published, use --source checkout.