Backup and restore of persistent service data for the
stack tool's Docker deployment mode.
Status: in use. Built and exercised end-to-end by
tests/backup/run-test.shin thestackrepo, which is where the documentation lives:docs/backup.md.
bozemanpass/backup — a small Alpine image bundling:
- restic — the backup engine: mandatory client-side encryption, deduplication, and native S3 support, so commodity object storage can be used safely;
- a cron scheduler;
- the Docker CLI — used to run application-consistency hooks (e.g.
pg_dump) inside the target service container, the same way the ingress proxy uses the Docker socket.
On Kubernetes the equivalent role is played by K8up, also restic-based. This repo covers
the Docker case only, but the two write the same layout -- one snapshot per volume, recorded at
/data/<volume> -- so a repository written by either can be restored by the other.
| Path | Purpose |
|---|---|
stacks/backup/stack.yml | Stack definition — declares the container and the pod. |
backup/composefile.yml | The canonical backup service. stack deploy appends mounts of the application's data volumes here when backup is enabled, at /data/<volume> -- read-write, because restoring writes back through them. |
containers/backup/ | The bozemanpass/backup image: Containerfile, build.sh, and scripts/. |
The image entrypoint takes a mode argument (default schedule):
| Mode | Action |
|---|---|
schedule | Install a cron entry (BACKUP_SCHEDULE) that runs backup periodically. |
backup | Run hooks, then one restic backup per volume mounted under /data, then apply retention. |
restore [snapshot] [volume…] | Restore a snapshot into the (rw-mounted) volumes, all of them or only those named. Default latest. Never creates a repository: restoring from one that is not there is a mistake, not an empty backup. |
list | One <id> <date> <volume,volume> line per snapshot -- the format stack manage … backup list prints. |
prune | Apply the retention policy (restic forget --prune). |
check | Verify repository integrity. |
Supplied by stack from the deployment environment (see docs/backup.md for the profile keys):
| Variable | Purpose |
|---|---|
BACKUP_S3_ENDPOINT, BACKUP_S3_BUCKET | Object store location (or set RESTIC_REPOSITORY directly). |
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY | Object store credentials. |
RESTIC_PASSWORD | Encryption key — mandatory. Without it the repository is unreadable. |
BACKUP_SCHEDULE | Cron schedule (default 0 3 * * *). |
BACKUP_RETENTION | forget/prune flags (default --keep-daily 7 --keep-weekly 4 --keep-monthly 6). |
BACKUP_PRE_HOOKS | service:command:ext;… consistency dumps. Scaffolded here but never set by stack -- the annotations that would generate it are parsed no further; see "Not built yet" in docs/backup.md. |
RESTIC_REPOSITORY | Set directly to override where a run reads/writes, which is how backup restore --from points one restore at another deployment's repository. |
stack fetch repo bozemanpass/backup-stack
stack prepare --stack backup # builds bozemanpass/backup:stack# Backup is then enabled per-deployment via the `backup` config switch; see docs/backup.md.