docker-compose-backup

A backup tool for Docker Compose projects with minimal downtime — stop, copy, restart (seconds), then compress after the service is back online.

How It Works

docker compose stop — stops the containers
copy — copies the entire project directory to a staging area
docker compose up -d — restarts containers immediately (downtime ends here)
tar.gz — compresses the snapshot into the backup directory after restart
Optional: upload to S3 / WebDAV
Retention: auto-deletes old backups per policy

Installation

go build -o docker-compose-backup .
# or cross-compile:
GOOS=linux GOARCH=arm64 go build -o docker-compose-backup-linux-arm64 .

Quick Start

Copy and edit the config:

cp config.example.yaml config.yaml

Run a backup:

./docker-compose-backup backup -c config.yaml

List configured projects and existing backups:

./docker-compose-backup list -c config.yaml

Run as a daemon with cron scheduling:

./docker-compose-backup daemon -c config.yaml

systemd deployment

This repository includes docker-compose-backup.service, configured for installation under /opt/docker-compose-backup:

sudo mkdir -p /opt/docker-compose-backup
sudo cp docker-compose-backup-linux-arm64 /opt/docker-compose-backup/docker-compose-backup
sudo chmod +x /opt/docker-compose-backup/docker-compose-backup
sudo cp config.yaml /opt/docker-compose-backup/config.yaml
sudo mkdir -p /opt/docker-compose-backup/backups
sudo cp docker-compose-backup.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now docker-compose-backup

The example config uses /opt/docker-compose-backup/backups, which is allowed by the service sandbox.

Configuration

See config.example.yaml for a full annotated example.

global:
  backup_dir: /opt/docker-compose-backup/backups
  temp_dir: /tmp/docker-backup       # optional, defaults to OS temp

projects:
  - name: myapp
    path: /opt/docker/myapp
    compose_file: docker-compose.yml  # default
    cron: "0 3 * * *"                # optional: daily at 3 AM, standard 5-field cron
    exclude:
      - ".git"
      - "node_modules"
    retention:
      count: 7                       # keep last 7 backups
      days: 30                       # optional: also delete >30 days

# Optional: remote upload
# remote:
#   s3:
#     endpoint: https://s3.example.com
#     bucket: my-backups
#     access_key: ${S3_ACCESS_KEY}
#     secret_key: ${S3_SECRET_KEY}
#     region: us-east-1
#     path_prefix: docker-backups/
#   webdav:
#     url: https://webdav.example.com/backups
#     username: user
#     password: ${WEBDAV_PASSWORD}

Environment variables in ${VAR} form are expanded automatically.

exclude uses Go filepath.Match patterns and also matches each file/directory basename. It is not full .gitignore syntax: ** and negation rules like !foo are not supported.

Commands

Command	Description
`backup`	Run backup for all projects, print summary
`list`	List configured projects and their existing backups
`daemon`	Run as a background daemon with cron scheduling

Global flags:

Flag	Description
`-c, --config`	Path to config file (default: `config.yaml`)
`--dry-run`	Print actions without executing
`--version`	Print version

Requirements

Docker CLI accessible on PATH
Go 1.26+ (to build from source)

3.7 KiB Raw Blame History