{"slug": "automated-docker-compose-backups-with-restic-verified-snapshot-and-restore", "title": "Automated Docker Compose Backups with Restic: Verified Snapshot and Restore", "summary": "A developer published a Docker Compose stack that automates verified PostgreSQL backups using Restic, splitting the work into three short-lived stages: a Postgres 16 database with a pg_isready healthcheck, a pg_dumper job that writes a non-empty pg_dump to a shared staging volume, and a backup-verify job that initializes the Restic repository, backs up the staging volume, runs restic check --read-data, restores the latest snapshot, and asserts a marker row is present. The staging volume is mounted read-only into the verify container so the backup job cannot mutate the dump it checks, and all state lives in named volumes with no host bind mounts or Docker socket.", "body_md": "This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.\n\nThis stack separates concerns into three short-lived, deterministic stages:\n\n`db`` postgres:16-alpine` instance with a named volume `pg_data`. It exposes a `pg_isready` healthcheck so downstream jobs wait for a real database, not just a listening socket.`pg-dumper`` pg_dump` into a shared staging volume, and exits 0 only if the dump file is non-empty. It uses the same `backup-verify`` restic/restic:0.17.3` container that initializes the repository if needed, backs up `/staging`, runs `restic check --read-data`, restores the latest snapshot into `/tmp/restore-test`, and asserts the marker text is present. It exits 0 only when the full round-trip succeeds.\nAll persistent state lives in named volumes (`pg_data`, `backup_staging`, `restic_repo`). No host bind mounts, no Docker socket. The entire stack is defined in a single `compose.yml` plus a `.env` file, so it runs identically in a sandbox and on a VPS.\n\nThe staging volume is mounted read-only into `backup-verify`, which enforces a clean boundary: the backup job cannot mutate the dump it is verifying. The Restic repository is local by default (`/repo`), but the same container works unchanged against S3-compatible object storage by swapping `RESTIC_REPOSITORY`.\n\n`check --read-data` reads the entire repository, so keep the staging volume small (a few hundred MB) or move the repository to object storage.`RESTIC_PASSWORD` in `.env`. Losing it means losing the ability to decrypt backups.\nCreate the project directory and write both files:\n\n```\nmkdir -p restic-backup && cd restic-backup\ncat <<'EOF' > compose.yml\nservices:\n  db:\n    image: postgres:16-alpine\n    environment:\n      POSTGRES_USER: ${POSTGRES_USER:-app}\n      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}\n      POSTGRES_DB: ${POSTGRES_DB:-appdb}\n    volumes:\n      - pg_data:/var/lib/postgresql/data\n    healthcheck:\n      test: [\"CMD-SHELL\", \"pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}\"]\n      interval: 5s\n      timeout: 5s\n      retries: 20\n    restart: unless-stopped\n\n  pg-dumper:\n    image: postgres:16-alpine\n    depends_on:\n      db:\n        condition: service_healthy\n    environment:\n      PGHOST: db\n      PGUSER: ${POSTGRES_USER:-app}\n      PGPASSWORD: ${POSTGRES_PASSWORD}\n      PGDATABASE: ${POSTGRES_DB:-appdb}\n    volumes:\n      - backup_staging:/staging\n    configs:\n      - source: dump_script\n        target: /usr/local/bin/dump.sh\n        mode: 0755\n    entrypoint: [\"/bin/sh\", \"/usr/local/bin/dump.sh\"]\n    restart: \"no\"\n\n  backup-verify:\n    image: restic/restic:0.17.3\n    depends_on:\n      pg-dumper:\n        condition: service_completed_successfully\n    environment:\n      RESTIC_REPOSITORY: ${RESTIC_REPOSITORY:-/repo}\n      RESTIC_PASSWORD: ${RESTIC_PASSWORD}\n    volumes:\n      - backup_staging:/staging:ro\n      - restic_repo:/repo\n    entrypoint: [\"/bin/sh\", \"-ec\"]\n    command:\n      - |\n        restic snapshots >/dev/null 2>&1 || restic init\n        restic backup /staging\n        restic check --read-data\n        rm -rf /tmp/restore-test\n        restic restore latest --target /tmp/restore-test\n        test -s /tmp/restore-test/staging/appdb.sql\n        grep -q 'restic-marker' /tmp/restore-test/staging/appdb.sql\n        echo \"backup-verify: snapshot, check, and restore OK\"\n    restart: \"no\"\n\nconfigs:\n  dump_script:\n    content: |\n      #!/bin/sh\n      set -eu\n      psql -v ON_ERROR_STOP=1 <<'SQL'\n      CREATE TABLE IF NOT EXISTS restic_marker (\n        id integer PRIMARY KEY,\n        note text NOT NULL\n      );\n      INSERT INTO restic_marker (id, note)\n      VALUES (1, 'restic-marker')\n      ON CONFLICT (id) DO UPDATE SET note = EXCLUDED.note;\n      SQL\n      pg_dump -Fp -f /staging/appdb.sql\n      test -s /staging/appdb.sql\n      echo \"pg-dumper: wrote $(wc -c < /staging/appdb.sql) bytes to /staging/appdb.sql\"\n\nvolumes:\n  pg_data:\n  backup_staging:\n  restic_repo:\nEOF\n\ncat <<'EOF' > .env\nPOSTGRES_USER=app\nPOSTGRES_PASSWORD=replace-with-a-strong-db-password\nPOSTGRES_DB=appdb\nRESTIC_PASSWORD=replace-with-a-strong-restic-password\nRESTIC_REPOSITORY=/repo\nEOF\n```\n\nNotes on the design:\n\n`restic_marker`) so the restore check has a stable string to grep for. The `ON CONFLICT` clause makes re-runs idempotent.`pg_dump -Fc` produces a custom-format archive. It is compact and restorable with `pg_restore`, which is what you want for real databases.` restic_repo` volume is mounted at `/repo` and is the default `RESTIC_REPOSITORY`. When you switch to S3, the volume is simply unused.\nRun the pipeline once and inspect exit codes:\n\n```\ndocker compose up --abort-on-container-exit --exit-code-from backup-verify\n```\n\nYou should see `pg-dumper` log the byte count, then `backup-verify` log the snapshot, check, and restore confirmation. Both one-shot services must exit 0.\n\nInspect the repository and the restored file:\n\n```\ndocker compose run --rm backup-verify sh -ec 'restic snapshots'\ndocker compose run --rm backup-verify sh -ec 'restic ls latest'\n```\n\nIf you want to confirm the marker survived the round-trip without re-running the full pipeline:\n\n```\ndocker compose run --rm backup-verify sh -ec 'rm -rf /tmp/restore-test && restic restore latest --target /tmp/restore-test && grep -c restic-marker /tmp/restore-test/staging/appdb.sql'\n```\n\nTear down without losing data:\n\n```\ndocker compose down\n```\n\n`docker compose down -v` deletes `pg_data`, `backup_staging`, and `restic_repo`. Use it only when you intend to start from scratch.\n\nThis stack has no HTTP surface, so there is no HTTPS cutover. The production cutover is about moving the Restic repository off the VPS and scheduling the pipeline.\n\nSet the repository URL and credentials in `.env`. For Cloudflare R2:\n\n```\nRESTIC_REPOSITORY=s3:https://<account-id>.r2.cloudflarestorage.com/<bucket>\nAWS_ACCESS_KEY_ID=<r2-access-key>\nAWS_SECRET_ACCESS_KEY=<r2-secret-key>\n```\n\nFor Backblaze B2:\n\n```\nRESTIC_REPOSITORY=s3:https://s3.<region>.backblazeb2.com/<bucket>\nAWS_ACCESS_KEY_ID=<b2-key-id>\nAWS_SECRET_ACCESS_KEY=<b2-application-key>\n```\n\nFor AWS S3:\n\n```\nRESTIC_REPOSITORY=s3:s3.amazonaws.com/<bucket>\nAWS_ACCESS_KEY_ID=<aws-access-key>\nAWS_SECRET_ACCESS_KEY=<aws-secret-key>\n```\n\nAdd the AWS variables to the `backup-verify` service environment in `compose.yml` (or pass them via `docker compose run -e`). The `restic_repo` volume becomes unused in this mode; you can drop it from the service if you want a tighter definition.\n\nA systemd timer is the most reliable option on a VPS. Create `/etc/systemd/system/restic-backup.service`:\n\n```\n[Unit]\nDescription=Restic backup pipeline\nAfter=docker.service\nRequires=docker.service\n\n[Service]\nType=oneshot\nWorkingDirectory=/opt/restic-backup\nExecStart=/usr/bin/docker compose run --rm pg-dumper\nExecStart=/usr/bin/docker compose run --rm backup-verify\n```\n\nAnd `/etc/systemd/system/restic-backup.timer`:\n\n```\n[Unit]\nDescription=Nightly Restic backup\n\n[Timer]\nOnCalendar=*-*-* 02:30:00\nPersistent=true\n\n[Install]\nWantedBy=timers.target\n```\n\nEnable with `systemctl enable --now restic-backup.timer`. A cron equivalent is:\n\n```\n30 2 * * * cd /opt/restic-backup && docker compose run --rm pg-dumper && docker compose run --rm backup-verify\n```\n\nRun retention after a successful backup. Add it to the timer or run it manually:\n\n```\ndocker compose run --rm backup-verify sh -ec 'restic forget --keep-daily 7 --keep-weekly 4 --prune'\n```\n\n`--prune` rewrites pack files and can be slow on object storage. Run it weekly rather than nightly if bandwidth is a concern.\n\n**Upgrades.** Bump the Restic image tag in `compose.yml` and re-run the pipeline. Restic repositories are forward-compatible within a major version; check the release notes before crossing a major boundary. For PostgreSQL, the `pg_dump` format is stable across minor versions, but restoring into a newer major requires `pg_restore` from that major.\n\n**Failure modes.**\n\n`depends_on: service_completed_successfully` on **Backups of the backup.** The `restic_repo` volume is itself a single point of failure in local mode. For anything beyond a sandbox, use S3-compatible storage so the repository lives off the VPS. If you must stay local, snapshot the volume with your provider's block-storage snapshots.\n\n**Trade-offs.**\n\n`restic check` nightly.\n**Restore drill.** Once a quarter, restore a snapshot into a scratch database and run your application's smoke tests against it. The automated grep proves the file is intact; only a real restore proves the data is usable.\n\n**Measured in our sandbox run:** total memory 24.9 MB (sum of per-container peaks over a 30s idle window after startup) across 3 containers; largest container 24.9 MB. The run took 49.9s with the image already cached; a fresh server also has to download it. Required secret(s) POSTGRES_PASSWORD, RESTIC_PASSWORD were generated for the test run, as the tutorial instructs. Verified one-shot jobs: backup-verify (exit 0), pg-dumper (exit 0).\n\n*Verification: we ran this docker-compose stack in a disposable Docker environment and recorded the measurements above. They describe that run, not a guarantee for your host.*\n\n*Originally published with full interactive benchmark metrics and server sizing notes at [https://vpsfolio.pages.dev/stacks/docker-compose-automated-restic-backup-restore/](https://vpsfolio.pages.dev/stacks/docker-compose-automated-restic-backup-restore/).*", "url": "https://wpnews.pro/news/automated-docker-compose-backups-with-restic-verified-snapshot-and-restore", "canonical_source": "https://dev.to/gongkang/automated-docker-compose-backups-with-restic-verified-snapshot-and-restore-4o1o", "published_at": "2026-11-20 03:38:33+00:00", "updated_at": "2026-11-20 03:43:14.445602+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools"], "entities": ["Docker", "Restic", "PostgreSQL"], "also_reported_by": [], "takeaway": "Mounting the staging volume read-only into the Restic verify container and gating on restic check --read-data plus a marker-grep restore test turns a backup job into a self-verifying round-trip that exits 0 only when the snapshot is restorable.", "recommendation": {"advice": "Run restic check --read-data and a restore-and-grep test in a separate container with the staging volume mounted read-only, and keep that volume small or move the repository to object storage since --read-data reads the entire repo.", "playbook": "production-ops", "playbook_url": "https://wpnews.pro/playbooks/production-ops"}, "alternates": {"html": "https://wpnews.pro/news/automated-docker-compose-backups-with-restic-verified-snapshot-and-restore", "markdown": "https://wpnews.pro/news/automated-docker-compose-backups-with-restic-verified-snapshot-and-restore.md", "text": "https://wpnews.pro/news/automated-docker-compose-backups-with-restic-verified-snapshot-and-restore.txt", "jsonld": "https://wpnews.pro/news/automated-docker-compose-backups-with-restic-verified-snapshot-and-restore.jsonld"}}