Backups

Database dumps and restore procedures for the Sancho Docker Compose deployment. Persistent state lives under ./data/ next to the compose file — see Persistent data.

Automated Postgres backup to S3

The postgres-backup service is optional — it is defined in docker-compose.yaml but only starts when the backup Compose profile is active. To enable, add to .env:

COMPOSE_PROFILES=backup        # or backup,garage

Then docker compose up -d. Without that, BACKUP_S3_BUCKET is ignored and no dumps run. If you operate Postgres backups out-of-band (host-level snapshot, managed Postgres replica, etc.), leave the profile off.

The service (image: prodrigestivill/postgres-backup-local:18-s3) runs pg_dump daily at 02:00 UTC, gzips the dump, and uploads it to S3 using the same credentials configured for the api (S3_ENDPOINT, S3_API_KEY, S3_API_SECRET).

Same-host caveat for backup + garage

If you also enable COMPOSE_PROFILES=backup,garage, the backup lands in the in-stack Garage instance — i.e. on the same disk as Postgres. That’s useful but not disaster recovery: a host failure loses both the database and the backups. Snapshot ./data/garage/ to off-site storage, or point S3_ENDPOINT at an external provider for the backup.

Garage operators: create the bucket once

The api auto-creates its own avatar / account buckets in Garage, but not BACKUP_S3_BUCKET — postgres-backup will fail silently at 02:00 UTC if the bucket is missing. Run this once after the first up -d:

docker compose exec garage /garage bucket create "$BACKUP_S3_BUCKET"
docker compose exec postgres-backup /backup.sh     # force one dump to verify

• Destination: the ${BACKUP_S3_BUCKET} bucket, dumps under daily/, weekly/, monthly/ subfolders. Dumps use pg_dump’s custom format (--format=custom) — restore with pg_restore.
• Retention: 28 daily, 4 weekly, and 4 monthly backups (BACKUP_KEEP_DAYS=28, BACKUP_KEEP_WEEKS=4, BACKUP_KEEP_MONTHS=4). Older dumps are pruned automatically.
• Requirement: BACKUP_S3_BUCKET must be set in .env and the bucket must exist (on external S3, pre-create it; on Garage, see the Aside above). The service crash-loops with a clear error if the bucket is missing or the credentials are wrong.
• Logs: docker compose logs -f postgres-backup — each run reports size, duration, and pruning.

To verify a backup worked without waiting until 02:00, force one on demand:

docker compose exec postgres-backup /backup.sh

Ad-hoc / full backup

# Database dump to a local file
docker compose exec postgres pg_dump -U $PG_USER $PG_DB | gzip > "sancho-$(date +%F).sql.gz"

# Full data tree (postgres + rabbitmq + redis + caddy state)
sudo tar -czf "sancho-data-$(date +%F).tar.gz" data/

Also back up your S3 bucket contents (the api’s buckets) — handled by your storage provider.

Restore

From an automated S3 backup

Fetch the dump from S3 (any S3 client works), then apply it to the database:

mc cp <alias>/$BACKUP_S3_BUCKET/daily/sancho-YYYY-MM-DD.sql.gz ./
gunzip -c sancho-YYYY-MM-DD.sql.gz | docker compose exec -T postgres pg_restore -U $PG_USER -d $PG_DB --clean --if-exists

From a local pg_dump

gunzip -c sancho-YYYY-MM-DD.sql.gz | docker compose exec -T postgres psql -U $PG_USER $PG_DB

From the full data tree

Stop the stack before restoring:

docker compose down
sudo tar -xzf sancho-data-YYYY-MM-DD.tar.gz
docker compose up -d