Black Friday mini PC deals are live, checked daily through Cyber Monday. See the deals guide
← All Guides
intermediate

Docker Volume Backups That Actually Restore

Back up Docker volumes the right way: tar through a throwaway container, database dumps, and a restore drill that proves the data comes back intact.

Budget Homelab ·
dockerbackuphow-toself-hosting

This guide contains no paid affiliate links. It is configuration, not shopping.

Every Docker Compose stack you add creates data you will eventually need back: a database, an uploads folder, a config directory the app generated on first start. The container is disposable. The volume behind it is not, and most homelab backup plans quietly skip it. A VM-level backup captures it by accident, but nothing in that plan tells you whether one app’s data would come back cleanly.

This guide covers the volume side of the homelab backup strategy: how to back up Docker volumes consistently, how to handle databases, and how to prove a restore works before you need one. It is the middle layer between whole-guest backups (Proxmox snapshots and backups, Proxmox Backup Server) and the off-site file copy in restic for homelab backups.

All hostnames, volume names, and paths below are examples. Substitute your own.

Quick Answer

# Flat-file volume: tar it through a throwaway container
docker run --rm \
  -v myapp_data:/source:ro \
  -v /srv/backups:/backup \
  alpine tar czf /backup/myapp_data-$(date +%F).tar.gz -C /source .

# Postgres: dump it, do not copy its files
docker exec -t myapp-db pg_dump -U myuser -Fc mydb > /srv/backups/mydb-$(date +%F).dump

Then restore one of them into a scratch volume and look at it. That last part is what the rest of this guide is about.

What Actually Needs Backing Up

Three things, and only three:

  1. The data. Named volumes and bind-mounted directories.
  2. The definition. The docker-compose.yml, the .env file, and any config files you bind-mount.
  3. The version. The image tag you were running, which lives in the compose file if you pinned it.

Images do not need a backup. They come from a registry or a Dockerfile you already have. What bites people is the second and third items: data restored into a stack whose compose file is gone, or into a newer image whose database format changed.

Start by listing what you have:

docker volume ls
docker compose config --volumes
docker inspect --format '{{ range .Mounts }}{{ .Type }} {{ .Name }} {{ .Source }} -> {{ .Destination }}{{ println }}{{ end }}' myapp

The last command prints each mount’s type, name, host source, and container path. A mount of type volume is a named volume. A mount of type bind is a host directory, which a file-level tool like restic can back up directly.

Two traps worth knowing now:

Sort Each Volume by How It Writes

The right method depends on what is writing to the volume while you copy it.

ClassExamplesSafe to copy while running?Method
Flat filesUploads, media metadata, config directoriesUsuallytar through a helper container
SQLiteMany small apps, password managers, dashboardsNo, can be mid-writeStop the container, or use SQLite’s own backup command
Database serverPostgres, MariaDB, MySQLNoDump with the database’s own tool

“Usually” for flat files is doing real work. Files that change during the copy can end up inconsistent with each other, such as an index that points at a file that was just replaced. For low-traffic apps this is a small risk. For anything you actively use during the backup window, schedule the job for when nobody is.

Method 1: Tar Through a Throwaway Container

This is the general-purpose method. It needs nothing installed on the host and does not depend on where Docker stores its data.

docker run --rm \
  -v myapp_data:/source:ro \
  -v /srv/backups:/backup \
  alpine tar czf /backup/myapp_data-$(date +%F).tar.gz -C /source .

What each piece does:

The container runs as root, so tar records file ownership. That matters on restore, because apps often run as a specific non-root UID and refuse to start if their files belong to someone else.

To restore into an empty volume:

docker volume create myapp_data_restored
docker run --rm \
  -v myapp_data_restored:/target \
  -v /srv/backups:/backup:ro \
  alpine tar xzf /backup/myapp_data-2026-11-05.tar.gz -C /target

Restoring into a new volume name first, rather than over the original, is the habit to build. It lets you inspect the result without risking the live data.

Method 2: Dump the Database

Never treat a database server’s data directory as a file you can copy while it runs. Use the dump tool shipped with the database.

Postgres:

docker exec -t myapp-db pg_dump -U myuser -Fc mydb > /srv/backups/mydb-$(date +%F).dump

-Fc writes the compressed custom format, which pg_restore can read selectively. To restore into a running Postgres container:

docker exec -i myapp-db pg_restore -U myuser -d mydb --clean --if-exists < /srv/backups/mydb-2026-11-05.dump

For a whole server with multiple databases and roles, pg_dumpall produces plain SQL for everything, at the cost of the selective restore.

MariaDB:

docker exec myapp-db sh -c 'mariadb-dump -u root -p"$MARIADB_ROOT_PASSWORD" --single-transaction --all-databases' > /srv/backups/mariadb-$(date +%F).sql

--single-transaction gives a consistent snapshot for InnoDB tables without locking them. The single quotes make the container expand the password variable, so the secret never appears on your host’s command line. Older MariaDB and MySQL images ship mysqldump instead of mariadb-dump, so check which one your image provides.

SQLite: if the container has the sqlite3 binary, the .backup command writes a consistent copy of a live database:

docker exec myapp sqlite3 /data/app.db ".backup '/data/app-backup.db'"

Many slim images do not include sqlite3. In that case stop the container instead (Method 3).

A dump file is a text or archive file in your backup directory. It then gets picked up by whatever copies that directory off the host, the same as any other file.

Method 3: Stop, Copy, Start

When an app has no dump tool and is not safe to copy hot, the dependable answer is a short outage:

cd /opt/stacks/myapp
docker compose stop app
docker run --rm -v myapp_data:/source:ro -v /srv/backups:/backup \
  alpine tar czf /backup/myapp_data-$(date +%F).tar.gz -C /source .
docker compose start app

Stop only the container that writes to the volume. Leaving a database container running while its app is stopped is fine, because nothing is changing the data. Run this at a quiet hour and the downtime is the length of the tar, which for config-sized volumes is seconds.

Back Up the Stack Definition Too

Data without the compose file is a puzzle. Copy the definition next to it:

tar czf /srv/backups/myapp-stack-$(date +%F).tar.gz -C /opt/stacks myapp

This captures docker-compose.yml, the .env file, and any bind-mounted config under the stack directory. Two cautions:

If you manage stacks through a UI such as Portainer, the volumes still live on the Docker host and still need this treatment. The UI does not back up their contents.

A Small Script That Does All of It

Put the pieces in one script and run it from a systemd timer or cron. Keep the volume list explicit, so a new volume does not silently join or miss the job.

#!/usr/bin/env bash
set -euo pipefail

BACKUP_DIR=/srv/backups/docker
DATE=$(date +%F)
KEEP_DAYS=14
VOLUMES=("myapp_data" "wiki_data" "notes_config")

mkdir -p "$BACKUP_DIR"

for vol in "${VOLUMES[@]}"; do
  docker run --rm \
    -v "${vol}:/source:ro" \
    -v "${BACKUP_DIR}:/backup" \
    alpine tar czf "/backup/${vol}-${DATE}.tar.gz" -C /source .
done

docker exec -t myapp-db pg_dump -U myuser -Fc mydb > "${BACKUP_DIR}/mydb-${DATE}.dump"

tar czf "${BACKUP_DIR}/stacks-${DATE}.tar.gz" -C /opt stacks

find "$BACKUP_DIR" -type f -mtime +"$KEEP_DAYS" -delete

set -euo pipefail makes the script stop on the first failure instead of cheerfully reporting success after a failed dump. The local retention here is a convenience. It is not the retention policy for your off-site copy. Let restic or your backup tool of choice handle history there, and treat /srv/backups/docker as a staging directory it reads from.

Add a final check that fails loudly if a file is missing or empty. A job that exits zero while writing a 0-byte archive is the classic silent failure:

for f in "${BACKUP_DIR}"/*-"${DATE}".*; do
  [ -s "$f" ] || { echo "empty backup: $f" >&2; exit 1; }
done

The Restore Drill

A backup you have never restored is an assumption. The drill takes a few minutes and is the reason this guide exists.

  1. Restore into a scratch volume, never the live one (see Method 1).
  2. Compare contents. List the restored volume and spot-check file counts and sizes against the source:
    docker run --rm -v myapp_data:/a:ro -v myapp_data_restored:/b:ro alpine \
      sh -c 'cd /a && find . -type f | wc -l; cd /b && find . -type f | wc -l'
  3. Start the app against the restored data. Copy the compose file to a scratch directory, change the volume name to myapp_data_restored and the published port to an unused one, then bring it up. Log in. Open something you know should be there.
  4. For databases, restore the dump into a throwaway container, not your running one:
    docker run -d --name restore-test -e POSTGRES_PASSWORD=scratch postgres:16
    docker exec -i restore-test pg_restore -U postgres -d postgres --create < /srv/backups/mydb-2026-11-05.dump
    docker exec restore-test psql -U postgres -d mydb -c '\dt'
    Use the same Postgres major version as the source. A dump generally restores into the same or a newer version, not an older one.
  5. Delete the scratch volumes and containers when you are done.

Put the drill on a calendar. Redo it after any change to the stack: a new database version, a new volume, a moved storage path.

Why Restores Fail

Most restore failures are boring, and most of them are visible in the drill.

SymptomLikely causeFix
App starts with an empty stateRestored into a differently named volume than the compose file mountsCheck the real volume name with docker volume ls, mind the project prefix
Permission denied on startupOwnership changed during copyCreate the archive as root so tar records ownership, and extract as root
Database refuses to startRaw files copied from a live server, or a different major versionRestore from a dump; pin the image tag
Restore works but data is hours oldBackup ran, but the off-site copy did notCheck the copy job’s last run, not just the dump’s
Archive is tinyWrong path in -C, or an empty volume mountedCheck the file size in the job and fail on empty files
Nested source/ directory after restoreArchived the path instead of its contentsUse -C /source . as shown

Where This Fits

Volume backups sit between two other layers, and each covers a gap in the others:

Run all three if you can. If you can only run one thing this week, back up the databases and run a restore drill on one of them.

Next Steps