Backup & Restore

Dockflow provides built-in backup and restore for accessory databases, main stack services, and Docker volumes. Back up PostgreSQL, MySQL, MongoDB, Redis, Docker volumes, or any custom service with a single command.

Configuration

Add a backup section to your .dockflow/config.yml. Backup targets can be declared under accessories (for services in accessories.yml) or services (for services in your main docker-compose.yml):

backup:
  retention_count: 10    # Backups to keep per service (default: 10)
  compression: gzip      # gzip or none (default: gzip)
  accessories:
    postgres:
      type: postgres
      dump_options: "--no-owner --clean"
    redis:
      type: redis
  services:
    app:
      type: volume
    mongodb:
      type: mongodb

Accessory Configuration

Each entry under backup.accessories maps to a service name in your accessories.yml:

Service Configuration

Each entry under backup.services maps to a service name in your main docker-compose.yml. This is useful when you have a single-service stack without accessories, or when you need to back up volumes or data from your main application containers.

backup:
  services:
    app:
      type: volume
    custom-db:
      type: raw
      dump_command: "mydb-dump --stdout"
      restore_command: "mydb-restore --stdin"

The same fields are available as for accessory configuration:

Commands

Create a Backup

dockflow backup create <env> <service>

Runs the appropriate dump command inside the running container and stores the compressed output on the server.

dockflow backup create production postgres
# ✓ Backup created
# Backup ID: 20260309-143052-a3f1
# Size: 12.5 MB
# Duration: 3.2s

List Backups

dockflow backup list <env> [service]
dockflow backup list production           # All services
dockflow backup list production postgres  # Specific service
dockflow backup list production --json    # JSON output

Restore from a Backup

dockflow backup restore <env> <service>
dockflow backup restore production postgres              # Restore latest
dockflow backup restore production postgres --from 20260309-143052-a3f1  # Specific backup
dockflow backup restore production postgres --yes        # Skip confirmation

Prune Old Backups

dockflow backup prune <env> [service]
dockflow backup prune production               # All services
dockflow backup prune production postgres      # Specific service
dockflow backup prune production --keep 5      # Override retention count

Supported Database Types

PostgreSQL

Uses pg_dump and psql. Credentials are automatically read from the container’s POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB environment variables.

backup:
  accessories:
    postgres:
      type: postgres
      dump_options: "--no-owner --clean --if-exists"

MySQL

Uses mysqldump and mysql. Credentials are read from MYSQL_USER (or root), MYSQL_ROOT_PASSWORD / MYSQL_PASSWORD, and MYSQL_DATABASE.

backup:
  accessories:
    mysql:
      type: mysql
      dump_options: "--single-transaction --quick"

MongoDB

Uses mongodump --archive and mongorestore --archive. Credentials are read from MONGO_INITDB_ROOT_USERNAME, MONGO_INITDB_ROOT_PASSWORD, and MONGO_INITDB_DATABASE.

backup:
  accessories:
    mongodb:
      type: mongodb

Redis

Triggers BGSAVE and copies the RDB dump file. Restore writes the new dump file, issues SHUTDOWN NOSAVE to prevent Redis from overwriting it, then restarts the service (docker service update --force on Swarm, kubectl rollout restart on k3s).

backup:
  accessories:
    redis:
      type: redis

Custom (Raw)

For any other database, provide your own dump and restore commands. The commands run inside the container via docker exec.

backup:
  accessories:
    custom-db:
      type: raw
      dump_command: "mydb-dump --stdout"
      restore_command: "mydb-restore --stdin"

The dump command must write to stdout. The restore command must read from stdin.

Volume

Backs up all persistent data associated with a service container: Docker named volumes and read-write bind mounts (host-mounted directories). Named volumes are archived via a temporary Alpine container, while bind mounts are tarred directly from the host filesystem.

Ideal for services where data lives in volumes or host-mounted paths rather than databases (e.g., file storage, MinIO, uploads).

backup:
  accessories:
    minio:
      type: volume
    uploads:
      type: volume
      exclude_volumes:
        - "*-temp"
        - "*-cache"
        - "/etc/localtime"

The system automatically discovers all named volumes and read-write bind mounts on the service container. Each produces a separate tar archive. Read-only bind mounts (e.g., config files) are excluded automatically.

Controlling what gets backed up

By default, all named volumes and read-write bind mounts are included. There are two ways to control this:

Disable bind mounts entirely — use include_bind_mounts: false to only back up Docker named volumes:

backup:
  services:
    app:
      type: volume
      include_bind_mounts: false  # Only named Docker volumes

Exclude specific mounts — use exclude_volumes with glob patterns to skip individual volumes or bind mounts. Patterns match against volume short names, full volume names, host source paths, and container destination paths:

backup:
  services:
    app:
      type: volume
      exclude_volumes:
        - "*-cache"            # Exclude volumes ending with -cache
        - "/etc/localtime"     # Exclude a specific bind mount by host path
        - "/app/tmp"           # Exclude by container destination path

Storage

Backups are stored on the manager server at:

# Accessory backups
/var/lib/dockflow/backups/{stack}-accessories/{service}/

# Main stack service backups
/var/lib/dockflow/backups/{stack}/{service}/

Example files:

20260309-143052-a3f1.sql.gz       # Compressed database dump
20260309-143052-a3f1.meta.json    # Metadata (size, duration, type)
20260308-020000-b7c2.sql.gz
20260308-020000-b7c2.meta.json
20260310-030000-c4d3.data.tar.gz  # Named volume backup
20260310-030000-c4d3.app-uploads.tar.gz  # Bind mount backup
20260310-030000-c4d3.meta.json

API

The WebUI exposes backup operations via REST:

Best Practices

• Back up before deployments: Run dockflow backup create before deploying schema migrations
• Set up regular backups: Use cron or your CI pipeline to schedule dockflow backup create
• Test restores: Periodically verify backups work by restoring to a staging environment
• Monitor disk usage: Backups accumulate on the server; use prune to keep disk usage in check
• Pin retention count: Set retention_count in config rather than relying on the default