Backups and restore

A pod backs itself up to its own disk every hour. That protects you from mistakes with Docker, not from losing the server. Set up off-host snapshots as soon as the pod holds anything you care about.

All commands run from the deploy directory:

cd /opt/synap/deploy

Where the data livesCopy Anchor Link

<project> is the Compose project name, pinned as COMPOSE_PROJECT_NAME in deploy/.env. docker volume ls lists the volumes.

What the pod does on its ownCopy Anchor Link

The postgres-backup service:

• dumps every database every hour (PG_BACKUP_INTERVAL_SECONDS, default 3600), reading each dump back before keeping it;
• keeps the newest 6 dumps (PG_BACKUP_KEEP) plus one per day for 7 days (PG_BACKUP_KEEP_DAILY);
• sets aside a dump of a database that suddenly became empty, marked SUSPECT, and raises an alarm instead of pruning or pushing anything;
• pushes good dumps off-host once a repository is set up, and runs a restore drill every week;
• reports itself unhealthy when there is no fresh dump or an alarm, a failed push or a failed drill.

Every synap update also takes a verified pre-update dump of every database before it runs migrations.

Set up off-host snapshotsCopy Anchor Link

Snapshots are encrypted on the pod with restic and sent to a repository you choose. Each snapshot holds every database dump, the files in MinIO, .env and the pod's state/ directory.

1. Set the repository and its credentials:

   Copy Text

   sudo synap config set BACKUP_REPOSITORY=rest:https://vault.example.com:8000/my-pod
   sudo synap config set BACKUP_RESTIC_REST_USERNAME=my-pod
   printf 'BACKUP_RESTIC_REST_PASSWORD=%s\n' '<password>' | sudo synap config set --stdin

   BACKUP_REPOSITORY also accepts s3:…, b2:<bucket>:<path> or a local path such as /mnt/backup. For S3 use BACKUP_AWS_ACCESS_KEY_ID, BACKUP_AWS_SECRET_ACCESS_KEY and BACKUP_AWS_DEFAULT_REGION; for Backblaze B2, BACKUP_B2_ACCOUNT_ID and BACKUP_B2_ACCOUNT_KEY. BACKUP_HEARTBEAT_URL is pinged after each successful push.

2. Create the repository:

   Copy Text

   sudo synap backup init

   It prints a recovery kit with the repository password, once, and asks you to type back its last six characters. Keep the kit in two places you control. Synap never has it, and without it the snapshots cannot be decrypted.

3. Check it:

   Copy Text

   sudo synap backup push      # take a snapshot now
   sudo synap backup status    # repository, last runs, alarms

The pod only ever adds snapshots; it never deletes them. Give it append-only credentials (a restic REST server with --append-only, or an S3 or B2 key without delete permission) and run retention where the delete-capable credentials live, for example:

restic forget --keep-hourly 24 --keep-daily 14 --keep-weekly 8 --keep-monthly 12 --prune

CommandsCopy Anchor Link

Both restore commands ask you to type yes before replacing anything.

Restore onto a new serverCopy Anchor Link

1. Point the pod's DNS records at the new server, and install the pod there with the same --domain (self-host quickstart). The restore replaces its .env with the one in the snapshot.

2. Set the same BACKUP_REPOSITORY and credentials with synap config set.

3. Restore the latest snapshot:

   Copy Text

   sudo synap restore --from-snapshot latest

4. If the stack does not start because the server has no images yet, run sudo synap update; it keeps the restored .env. Then check with sudo synap health.

Large file uploadsCopy Anchor Link

Large files are uploaded to storage in parts. If the pod is stopped in the middle of an upload, the parts already sent stay in the bucket. The bundled MinIO removes stale parts by itself after 24 hours. On AWS S3, add a lifecycle rule AbortIncompleteMultipartUpload (for example after one day) to the bucket, or you pay for the leftovers; on other S3-compatible stores, check their lifecycle settings.