Loading…
.jpg&w=3840&q=75)
← Handbook
Runbooks
A system isn't finished when it works — it's finished when someone else can operate it when it breaks. Every build ships with runbooks: deploy, rollback, incident response, and a plain-language handover. Below is a real, abridged example from a production literary platform.
.jpg&w=3840&q=75)
Zero-to-production
A dependency-ordered deploy
Ordered because order matters — seed users exist before the seed migration runs, env vars exist before the first deploy, the site URL is set before DNS cutover.
- 1
Provision data
Create the Supabase project in af-south-1 (Cape Town); create the auth users before the seed migration so profile/story seeds resolve by UUID; run migrations strictly in order; confirm storage buckets are set correctly.
- 2
Wire services
Verify the email domain (SPF / DMARC / DKIM), obtain a long-lived social access token, and create the AI key — each with its own checklist.
- 3
Configure & deploy
Add every environment variable before the first deploy (never after); deploy; set the canonical site URL and redeploy so auth links resolve.
- 4
DNS
Point the apex and www records, then re-verify the site URL so password-recovery and OAuth links are cross-device safe.
- 5
Smoke test
Run a fixed checklist after every deploy: homepage + cover render, podcast page, AI assistant responds, admin login + role-redirect, draft save, editorial handoff, a test newsletter send (under 2 min), and an image upload.
.jpg&w=3840&q=75)
When something breaks
Operational procedures
Reset a user password
Three documented paths — self-serve email, dashboard-triggered reset, and an emergency force-set.
Unpublish / soft-delete / restore
Move a story out of "published" (gone publicly within ~60s), soft-delete with deleted_at, or restore by clearing it — never a hard delete.
Newsletter send failure
Check provider logs for bounces/rate-limits, cross-reference active subscribers, retry per-recipient, and mark hard bounces unsubscribed.
Social post failure
An error-code map (expired token / permissions / content flag) plus a token-rotation runbook: regenerate, extend, update the env var, redeploy.
Diagnose an RLS error
Inspect the policy via pg_policies, distinguish the RLS-bound client from the service client, and test by switching roles.
Roll back a deploy
Read the build logs; roll back by promoting the previous good deployment to production; redeploy to pick up env changes.
.jpg&w=3840&q=75)
The handover
You own it — and you can run it.
Delivery includes a handover checklist written in plain language — what each remaining setting does, what a webhook is "in plain words," and a troubleshooting guide for the few dashboard-only steps. The code, the schema, the runbooks and the data are yours. This is the answer to the question every serious buyer asks about a small studio: what happens when you're not available? The system is documented well enough that the answer is "you, or anyone you hire, can keep going."
