Backup a Docker volume
This recipe shows how to back up a Docker volume by mounting it read-only into a temporary container, creating a tar stream on STDOUT, and letting the Backup Verified agent encrypt and upload the result.
What this recipe is for
This recipe is useful when application data lives in a Docker volume and you want a practical, container-friendly way to back it up without first copying the volume contents to a local folder.
The idea is simple: start a small temporary container, mount the target volume as read-only, create a tar stream from inside that container, and send the stream directly to the Backup Verified agent.
That gives you a clean backup workflow while keeping the archived volume data on STDOUT, where Backup Verified can encrypt it locally and upload only the encrypted result.
Good fit for
- Named Docker volumes
- Containerized app data
- Simple volume snapshots using tar
- Environments where a read-only mount is preferred
Not ideal for
- Cases where application consistency requires more than a simple file-level snapshot
- Highly specialized container storage workflows that need platform-specific backup tooling
Before you begin
- Install the Backup Verified agent.
- Make sure Docker is installed and working on the system that can access the volume.
- Create or obtain your bv-agent.yml config.
- Confirm the exact Docker volume name you want to protect.
Why this works
A temporary container can mount the Docker volume and create a tar stream directly from its contents. Because the tar output goes to STDOUT, the Backup Verified agent can read it immediately.
Using a read-only mount is a good default because the temporary container only needs to read the data, not modify it.
The recipe
Mount the volume read-only into a lightweight container and create a tar stream from the mounted path.
Step 1: Use this Docker command
docker run --rm \
-v my_volume:/data:ro \
alpine \
tar -cf - -C /data .Replace my_volume with the actual Docker volume name.
Step 2: Keep the archive on STDOUT
The command intentionally writes the tar archive to STDOUT instead of creating a local tar file first. That is what allows the Backup Verified agent to read, encrypt, and upload the backup in one flow.
The -C /data . portion tells tar to archive the contents of the mounted volume path cleanly.
Suggested BV config
This example uses a Docker volume tar stream as the backup command and gives the backup a clear identity inside Backup Verified.
# bv-agent.yml
bv:
api_base: "https://backupverified.com"
timeout_seconds: 30
work_timeout_seconds: 0
upload_timeout_seconds: 0
agent_key: "YOUR_AGENT_KEY"
client_encryption_key_b64: "YOUR_CLIENT_ENCRYPTION_KEY_B64"
backup:
source_key: "docker_volume_backup"
name: "Docker Volume Backup"
description: "Snapshot of Docker volume via tar stream"
delete_after_days: 0
source:
type: "docker"
backup_command: >
docker run --rm
-v my_volume:/data:ro
alpine
tar -cf - -C /data .The > after backup_command: is YAML formatting for multi-line text. It is not shell output redirection.
How to run it
bv-agent validate-config -config bv-agent.yml
bv-agent backup -config bv-agent.ymlValidate first, then run the backup. If Docker can access the volume and the tar stream succeeds, the encrypted backup should appear in your portal.
What success looks like
- The agent completes without error.
- Your Docker volume backup appears in the Backup Verified portal.
- You can later download the encrypted file and decrypt it locally.
- The decrypted output contains the archived volume contents you expected.
What could go wrong
Docker volume backups are straightforward, but there are a few common points worth checking carefully.
Wrong volume name
If the volume name is wrong, the command will fail or target the wrong data. Confirm the exact volume name before you run it.
Docker access problems
The system running the backup needs permission to run Docker and access the volume through the local Docker engine.
Assuming file snapshot means app consistency
A volume snapshot captures files. Some applications may need their own quiesce or dump procedure for the most reliable recovery.
The strength of this recipe is simplicity. For many workloads, it is a practical and repeatable way to protect container data.
How to download it later
- 1. Sign in to your Backup Verified portal.
- 2. Open the Docker volume backup entry you want.
- 3. Use the download option to retrieve the encrypted backup file.
- 4. Save it locally for the decrypt step.
The downloaded file is still encrypted. That is expected.
Why that matters
The archived volume data is stored encrypted. Backup Verified does not need the plaintext contents in order to store the backup.
Decryption happens locally with your own key material, so recovery remains under your control.
How to decrypt it locally
Once you have downloaded the encrypted backup file, use the agent to decrypt it locally.
bv-agent decrypt --in backup.bin.enc --out ./restore/ -config bv-agent.ymlReplace backup.bin.enc with your actual downloaded filename. The --out path is where the decrypted result will be written.
Then inspect the output
ls -lah ./restore/Confirm that the decrypted output contains the files and directories you expected from the volume.
Good habit
Do at least one real download-and-decrypt test early. It is the fastest way to confirm the workflow matches your expectations.
What restore means for this recipe
For a Docker volume backup, restore usually means taking the decrypted archive contents and putting them back into the correct volume or into a replacement volume.
In practice, many people first restore into a temporary location, inspect the files, and then copy them into the destination volume with a controlled process.
docker run --rm \
-v my_volume:/data \
-v "$(pwd)/restore:/restore:ro" \
alpine \
sh -c 'cp -a /restore/. /data/'The exact restore steps depend on your environment and how the application expects its data to be laid out.
Related recipes
These are natural companions to a Docker volume workflow.