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

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

Installation

Download a pre-built binary (recommended)

Download the latest release for your architecture:

# linux amd64
curl -fsSL -o docker-compose-backup https://git.misaka.ren/m1saka/docker-compose-backup/releases/download/latest/docker-compose-backup-linux-amd64
# linux arm64
curl -fsSL -o docker-compose-backup https://git.misaka.ren/m1saka/docker-compose-backup/releases/download/latest/docker-compose-backup-linux-arm64

chmod +x docker-compose-backup

Build from source

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

Quick Start

1. Copy and edit the config:

cp config.example.yaml config.yaml

2. Run a backup:

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

3. List configured projects and existing backups:

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

4. 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
# Download the latest release (pick amd64 or arm64 to match the host):
sudo curl -fsSL -o /opt/docker-compose-backup/docker-compose-backup \
  https://git.misaka.ren/m1saka/docker-compose-backup/releases/download/latest/docker-compose-backup-linux-arm64
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 /opt/docker-compose-backup/tmp
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. The unit's ReadWritePaths covers the whole install dir, so set global.temp_dir to a subdirectory there (e.g. /opt/docker-compose-backup/tmp). The unit intentionally does not enable PrivateTmp, since a private /tmp is often small and would be exhausted when copying large project directories.

Configuration

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

global:
  backup_dir: /opt/docker-compose-backup/backups
  temp_dir: /opt/docker-compose-backup/tmp  # 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)