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.
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:
- The data. Named volumes and bind-mounted directories.
- The definition. The
docker-compose.yml, the.envfile, and any config files you bind-mount. - 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:
- Anonymous volumes. A container started with a
VOLUMEinstruction and no named mount gets a volume with a random hash for a name. It still holds data, and it is easy to lose track of. Give every stateful path a name in the compose file. - Project name prefixes. Compose prefixes volume names with the project name, so
datain a stack calledmyappbecomesmyapp_data. A volume declaredexternal: truekeeps its exact name. Checkdocker volume lsfor the real name before scripting anything.
Sort Each Volume by How It Writes
The right method depends on what is writing to the volume while you copy it.
| Class | Examples | Safe to copy while running? | Method |
|---|---|---|---|
| Flat files | Uploads, media metadata, config directories | Usually | tar through a helper container |
| SQLite | Many small apps, password managers, dashboards | No, can be mid-write | Stop the container, or use SQLite’s own backup command |
| Database server | Postgres, MariaDB, MySQL | No | Dump 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:
-v myapp_data:/source:romounts the volume read-only, so the backup cannot modify what it is reading.-v /srv/backups:/backupmounts a host directory to write the archive into.-C /source .archives the contents of the volume, not the path, so the restore does not nest an extra directory.
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:
- The
.envfile holds secrets. The backup is now as sensitive as your password manager. Encrypt before it leaves the host. Restic does this by default, a plain rsync to another machine does not. - Pin your image tags.
image: postgres:16restores predictably.image: postgres:latestmay pull a new major version on the day you restore, and Postgres will not start against a data directory from a different major version.
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.
- Restore into a scratch volume, never the live one (see Method 1).
- 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' - Start the app against the restored data. Copy the compose file to a scratch directory, change the volume name to
myapp_data_restoredand the published port to an unused one, then bring it up. Log in. Open something you know should be there. - For databases, restore the dump into a throwaway container, not your running one:
Use the same Postgres major version as the source. A dump generally restores into the same or a newer version, not an older 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' - 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.
| Symptom | Likely cause | Fix |
|---|---|---|
| App starts with an empty state | Restored into a differently named volume than the compose file mounts | Check the real volume name with docker volume ls, mind the project prefix |
| Permission denied on startup | Ownership changed during copy | Create the archive as root so tar records ownership, and extract as root |
| Database refuses to start | Raw files copied from a live server, or a different major version | Restore from a dump; pin the image tag |
| Restore works but data is hours old | Backup ran, but the off-site copy did not | Check the copy job’s last run, not just the dump’s |
| Archive is tiny | Wrong path in -C, or an empty volume mounted | Check the file size in the job and fail on empty files |
Nested source/ directory after restore | Archived the path instead of its contents | Use -C /source . as shown |
Where This Fits
Volume backups sit between two other layers, and each covers a gap in the others:
- Whole-guest backups (Proxmox snapshots, Proxmox Backup Server) restore an entire VM or LXC. They are the safety net when the host itself is gone, and a blunt instrument when you need one app back.
- Volume and database backups (this guide) restore one application’s data without touching anything else on the host.
- Off-site file backups (restic) protect against losing the building. A backup on the same machine as the data is not a backup of the machine.
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
- Add the backup directory to your off-site restic job.
- Read the homelab disaster recovery guide for the order to rebuild things in.
- Move any anonymous volumes to named volumes in your compose files, then rerun the inventory step.