volume-backup

An utility to backup and restore Docker volumes. For more info, read my article on Medium.

It works just as well with Podman volumes, just prefix each command with podman instead of docker.

Warning

Make sure no container is using the volume before backup or restore, otherwise your data might be damaged. See Miscellaneous for instructions.

Tip

When using docker-compose, make sure to backup and restore volume labels. See Miscellaneous for more information.

Tip

I am doing my best to keep this utility backwards-compatible. However, if you are using it in production environment and you want to be sure that it doesn't break with the future updates, request a specific image digest, e.g.: docker run -v [volume-name]:/volume --rm --log-driver none loomchild/volume-backup@sha256:d598345843d8eb20e4b0da331d538eb9158b70bcaff56f7ba09f5ce1b6498019 backup > [archive-path]. You can find the last digest on Docker Hub or GHCR. Note that old unused images might get deleted.

Backup

Syntax:

docker run -v [volume-name]:/volume --rm --log-driver none loomchild/volume-backup backup > [archive-path]

For example:

docker run -v some_volume:/volume --rm --log-driver none loomchild/volume-backup backup > some_archive.tar.bz2

will archive volume named some_volume to some_archive.tar.bz2 archive file.

Note

The --log-driver none option is necessary to avoid storing an entire backup in a temporary stdout JSON file. More info in Docker logging documentation and in this issue.

Note

This method should not be used under PowerShell on Windows as no usable backup will be generated.

Backup to a file (deprecated)

Syntax:

docker run -v [volume-name]:/volume -v [output-dir]:/backup --rm loomchild/volume-backup backup [archive-name]

For example:

docker run -v some_volume:/volume -v /tmp:/backup --rm loomchild/volume-backup backup some_archive

will archive volume named some_volume to /tmp/some_archive.tar.bz2 archive file.

Restore

Syntax:

docker run -i -v [volume-name]:/volume --rm loomchild/volume-backup restore < [archive-path]

For example:

docker run -i -v some_volume:/volume --rm loomchild/volume-backup restore < some_archive.tar.bz2

will clean and restore volume named some_volume from some_archive.tar.bz2 archive file.

Note

Don't forget the -i switch for interactive operation.

Note

Restore will fail if the target volume is not empty (use -f flag to override).

Restore from a file (deprecated)

Syntax:

docker run -v [volume-name]:/volume -v [output-dir]:/backup --rm loomchild/volume-backup restore [archive-name]

For example:

docker run -v some_volume:/volume -v /tmp:/backup --rm loomchild/volume-backup restore some_archive

will clean and restore volume named some_volume from /tmp/some_archive.tar.bz2 archive file.

Miscellaneous

1. Upgrade / update volume-backup

   docker pull loomchild/volume-backup
   

2. volume-backup is also available from GitHub Container Registry (ghcr.io), to avoid DockerHub usage limits:

   docker pull ghcr.io/loomchild/volume-backup
   

   Then write ghcr.io/loomchild/volume-backup instead of just loomchild/volume-backup when running the utility.

3. Find all containers using a volume (to stop them before backing-up)

   docker ps -a --filter volume=[volume-name]
   

4. Exclude some files from the backup and send the archive to stdout

   docker run -v [volume-name]:/volume --rm --log-driver none loomchild/volume-backup backup -e [excluded-glob] > [archive-path]
   

5. Use different compression algorithm for better performance

   docker run -v [volume-name]:/volume --rm --log-driver none loomchild/volume-backup backup -c pigz > [archive-path]
   

6. Show simple progress indicator using verbose -v flag (works both for backup and restore)

   docker run -v [volume-name]:/volume --rm --log-driver none loomchild/volume-backup backup -v > [archive-path]
   

7. Pass additional arguments to the Tar utility using -x option

   docker run -v [volume-name]:/volume --rm --log-driver none loomchild/volume-backup backup -x --verbose > [archive-path]
   

8. Directly migrate the volume to a new host

   docker run -v [volume-name]:/volume --rm --log-driver none loomchild/volume-backup backup | ssh [receiver] docker run -i -v [volume-name]:/volume --rm loomchild/volume-backup restore
   

   In case there are no traffic limitations between the hosts you can trade CPU time for bandwidth by turning off compression via -c none option.

9. Volume labels are not backed-up or restored automatically, but they might be required for your application to work (e.g. when using docker-compose). If you need to preserve them, create a label backup file as follows: docker inspect [volume-name] -f "{{json .Labels}}" > labels.json. When restoring your data, target volume needs to be created manually with labels before launching the restore script: docker volume create --label "label1" --label "label2" [volume-name].