Skip to content

Operate

Backups

What to back up and how to restore.

Two things hold your data, plus one secret. Back all three up.

What Where How
The database Postgres pg_dump on a schedule, or your managed Postgres' backups and point-in-time recovery.
The files The files volume (local disk) or the S3 bucket Back up the volume or bucket, turn on bucket versioning, or replicate the bucket.
The secret BETTER_AUTH_SECRET Keep it in your secret manager. Without it a restored instance signs everyone out.
Terminal window
docker compose exec -T postgres pg_dump -U circi -Fc circi > circi-$(date +%F).dump

Restore into an empty database with pg_restore, then start the app. The database holds accounts, builds, reviews and comments, integration credentials (encrypted at rest), webhooks and the generated web push keys (unless you set VAPID_*), and the GitHub App credentials if you created the app from the dashboard.

Files are content-addressed and verified. The database and the files must be restored to about the same moment: a restored database pointing at files that are missing shows broken images; files without their database rows are collected as unused by the next retention pass after the grace period. For local disk, snapshot the volume right after the dump. For S3, versioning protects against deletes.

If a few files were lost, builds that reference them fail to load images, and a new upload of the same screenshot restores them (uploads are deduplicated only against verified files).

  1. Start a scratch stack. Give it the same BETTER_AUTH_SECRET.
  2. Restore the data. Load the dump with pg_restore and copy the files into its storage.
  3. Check it. Point PUBLIC_URL at the scratch stack, then run circi admin doctor.

A backup you haven't restored is a guess.