Skip to content

Backups

Back up PostgreSQL: pg_dump, or your provider’s backups and point-in-time recovery (the GKE Terraform module’s Cloud SQL has both). With blobs in PostgreSQL (the default), that’s everything.

Terminal window
docker compose -f deploy/docker-compose.yml --env-file deploy/.env exec -T postgres \
pg_dump -U runbook -Fc runbook > runbook-$(date +%F).dump

deploy/update.sh takes and verifies a dump before every update.

With blobs in GCS or S3, back up the bucket too, or turn on its versioning, and restore the two together.

A database backup is only half a restore without these:

Secret Why
RUNBOOK_WEBHOOK_SECRET_KEY (WEBHOOK_SECRET_KEY on Cloudflare) Seals webhook signing secrets. Without it, restored subscriptions can’t sign deliveries
RUNBOOK_AUTH_SECRET Signs session cookies. A new one signs everyone out
RUNBOOK_UPLOAD_SIGNING_KEY Signs file URLs. A new one only invalidates links already handed out

Tokens are stored as hashes, so a backup holds no usable token.

A project can be exported to a portable archive, a ZIP of a manifest, one NDJSON file per table and the blobs, and imported into another server of either edition. Secrets never travel: tokens, execution credentials, webhook signing secrets, verified-email bindings and delivery logs are left out, so tokens and webhook secrets are issued again on the new server.

Terminal window
runbook-server export --org org_… --project prod --out prod.zip
runbook-server import --in prod.zip --org org_…

On Cloudflare, export and import are GET /internal/portable/export and POST /internal/portable/import on the api Worker, which exist only while the RUNBOOK_OPERATOR_SECRET secret is set and need it in the x-runbook-operator-secret header. An import there is at most 10 MiB.

Restore into a scratch database now and then, start a server against it with the same secrets, and run runbook-server doctor. A backup you’ve never restored is a hope, not a backup.