aux4/docker-backup

Backup and restore commands for Docker volumes, contributed to the docker profile.

This package extends aux4/docker with a volume subcommand group containing backup and restore, which follow the backup provider contract used by aux4/backup. It can be used on its own, or registered as a provider so the orchestrator schedules, catalogs and prunes the backups for you.

Volumes are exported by running a temporary Alpine container that mounts the volume and tars its contents into a .tar.gz archive on the local filesystem. Restoring reverses the process: an Alpine container extracts the archive back into the volume.

No system dependencies beyond Docker itself are needed.

Installation

aux4 aux4 pkger install aux4/docker-backup

Usage

# Back up a Docker volume
aux4 aux4 docker volume backup my_volume --path ./backups/my_volume.tar.gz

# Split the destination into directory + file
aux4 aux4 docker volume backup my_volume --dir ./backups --file my_volume.tar.gz

# Restore into a new or existing volume
aux4 aux4 docker volume restore my_restored_volume --path ./backups/my_volume.tar.gz

# Restore without cleaning existing data (overlay)
aux4 aux4 docker volume restore my_volume --path ./backups/my_volume.tar.gz --clean false

backup prints a result manifest to stdout:

{
  "path": "./backups/my_volume.tar.gz",
  "bytes": 4096,
  "checksum": "5f2b...",
  "status": "success",
  "format": "docker-volume-tar"
}

Commands

| Command | Description | |---------|-------------| | aux4 docker volume backup | Export a Docker volume to a tar.gz archive | | aux4 docker volume restore | Import a tar.gz archive into a Docker volume |

backup

aux4 aux4 docker volume backup <volume> --path <file>
aux4 aux4 docker volume backup <volume> --dir <dir> --file <name>

| Option | Description | |--------|-------------| | <volume> | Docker volume name (positional argument) | | --path | Full path for the archive file (takes precedence over --dir/--file) | | --dir | Directory to write the archive into (combined with --file) | | --file | File name for the archive (combined with --dir) |

The destination directory is created if missing. When the resolved path has no extension, .tar.gz is added -- so an orchestrator can pass an extension-less base path and let this package name the artifact for its own format. The volume must exist or the command exits non-zero.

restore

aux4 aux4 docker volume restore <volume> --path <file> [--clean false]

| Option | Description | |--------|-------------| | <volume> | Docker volume name (created if it does not exist) | | --path | Full path to the archive to restore (takes precedence over --dir/--file) | | --dir | Directory containing the archive (combined with --file) | | --file | File name of the archive (combined with --dir) | | --clean | Remove existing volume data before restoring (default: true). Set to false to overlay |

Restore creates the target volume if it does not exist. By default, existing data in the volume is removed before extracting the archive. Pass --clean false to overlay the archive on top of what is already there.

Use with aux4/backup

Register a Docker volume as a backup target and the orchestrator handles scheduling, cataloging, retention and restores:

aux4 backup register app_data \
  --command "aux4 aux4 docker" \
  --dir /var/backups/app_data \
  --retain 7

aux4 backup run app_data --wait true
aux4 backup verify app_data
aux4 backup restore app_data

License

Apache-2.0