# Automated Docker Compose Backups with Restic: Verified Snapshot and Restore

> Source: <https://dev.to/gongkang/automated-docker-compose-backups-with-restic-verified-snapshot-and-restore-4o1o>
> Published: 2026-11-20 03:38:33+00:00

**Recommendation:** 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.
More in the playbook "Running AI in production": <https://wpnews.pro/playbooks/production-ops>

This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.

This stack separates concerns into three short-lived, deterministic stages:

`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.
All 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.

The 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`.

`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.
Create the project directory and write both files:

```
mkdir -p restic-backup && cd restic-backup
cat <<'EOF' > compose.yml
services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-app}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB:-appdb}
    volumes:
      - pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 20
    restart: unless-stopped

  pg-dumper:
    image: postgres:16-alpine
    depends_on:
      db:
        condition: service_healthy
    environment:
      PGHOST: db
      PGUSER: ${POSTGRES_USER:-app}
      PGPASSWORD: ${POSTGRES_PASSWORD}
      PGDATABASE: ${POSTGRES_DB:-appdb}
    volumes:
      - backup_staging:/staging
    configs:
      - source: dump_script
        target: /usr/local/bin/dump.sh
        mode: 0755
    entrypoint: ["/bin/sh", "/usr/local/bin/dump.sh"]
    restart: "no"

  backup-verify:
    image: restic/restic:0.17.3
    depends_on:
      pg-dumper:
        condition: service_completed_successfully
    environment:
      RESTIC_REPOSITORY: ${RESTIC_REPOSITORY:-/repo}
      RESTIC_PASSWORD: ${RESTIC_PASSWORD}
    volumes:
      - backup_staging:/staging:ro
      - restic_repo:/repo
    entrypoint: ["/bin/sh", "-ec"]
    command:
      - |
        restic snapshots >/dev/null 2>&1 || restic init
        restic backup /staging
        restic check --read-data
        rm -rf /tmp/restore-test
        restic restore latest --target /tmp/restore-test
        test -s /tmp/restore-test/staging/appdb.sql
        grep -q 'restic-marker' /tmp/restore-test/staging/appdb.sql
        echo "backup-verify: snapshot, check, and restore OK"
    restart: "no"

configs:
  dump_script:
    content: |
      #!/bin/sh
      set -eu
      psql -v ON_ERROR_STOP=1 <<'SQL'
      CREATE TABLE IF NOT EXISTS restic_marker (
        id integer PRIMARY KEY,
        note text NOT NULL
      );
      INSERT INTO restic_marker (id, note)
      VALUES (1, 'restic-marker')
      ON CONFLICT (id) DO UPDATE SET note = EXCLUDED.note;
      SQL
      pg_dump -Fp -f /staging/appdb.sql
      test -s /staging/appdb.sql
      echo "pg-dumper: wrote $(wc -c < /staging/appdb.sql) bytes to /staging/appdb.sql"

volumes:
  pg_data:
  backup_staging:
  restic_repo:
EOF

cat <<'EOF' > .env
POSTGRES_USER=app
POSTGRES_PASSWORD=replace-with-a-strong-db-password
POSTGRES_DB=appdb
RESTIC_PASSWORD=replace-with-a-strong-restic-password
RESTIC_REPOSITORY=/repo
EOF
```

Notes on the design:

`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.
Run the pipeline once and inspect exit codes:

```
docker compose up --abort-on-container-exit --exit-code-from backup-verify
```

You 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.

Inspect the repository and the restored file:

```
docker compose run --rm backup-verify sh -ec 'restic snapshots'
docker compose run --rm backup-verify sh -ec 'restic ls latest'
```

If you want to confirm the marker survived the round-trip without re-running the full pipeline:

```
docker 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'
```

Tear down without losing data:

```
docker compose down
```

`docker compose down -v` deletes `pg_data`, `backup_staging`, and `restic_repo`. Use it only when you intend to start from scratch.

This 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.

Set the repository URL and credentials in `.env`. For Cloudflare R2:

```
RESTIC_REPOSITORY=s3:https://<account-id>.r2.cloudflarestorage.com/<bucket>
AWS_ACCESS_KEY_ID=<r2-access-key>
AWS_SECRET_ACCESS_KEY=<r2-secret-key>
```

For Backblaze B2:

```
RESTIC_REPOSITORY=s3:https://s3.<region>.backblazeb2.com/<bucket>
AWS_ACCESS_KEY_ID=<b2-key-id>
AWS_SECRET_ACCESS_KEY=<b2-application-key>
```

For AWS S3:

```
RESTIC_REPOSITORY=s3:s3.amazonaws.com/<bucket>
AWS_ACCESS_KEY_ID=<aws-access-key>
AWS_SECRET_ACCESS_KEY=<aws-secret-key>
```

Add 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.

A systemd timer is the most reliable option on a VPS. Create `/etc/systemd/system/restic-backup.service`:

```
[Unit]
Description=Restic backup pipeline
After=docker.service
Requires=docker.service

[Service]
Type=oneshot
WorkingDirectory=/opt/restic-backup
ExecStart=/usr/bin/docker compose run --rm pg-dumper
ExecStart=/usr/bin/docker compose run --rm backup-verify
```

And `/etc/systemd/system/restic-backup.timer`:

```
[Unit]
Description=Nightly Restic backup

[Timer]
OnCalendar=*-*-* 02:30:00
Persistent=true

[Install]
WantedBy=timers.target
```

Enable with `systemctl enable --now restic-backup.timer`. A cron equivalent is:

```
30 2 * * * cd /opt/restic-backup && docker compose run --rm pg-dumper && docker compose run --rm backup-verify
```

Run retention after a successful backup. Add it to the timer or run it manually:

```
docker compose run --rm backup-verify sh -ec 'restic forget --keep-daily 7 --keep-weekly 4 --prune'
```

`--prune` rewrites pack files and can be slow on object storage. Run it weekly rather than nightly if bandwidth is a concern.

**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.

**Failure modes.**

`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.

**Trade-offs.**

`restic check` nightly.
**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.

**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).

*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.*

*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/).*
