feat: docker compose backup

2026-07-04 17:20:28 +08:00
commit 5c8944fd58
27 changed files with 2070 additions and 0 deletions
@@ -0,0 +1,124 @@
+# 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
+
+```bash
+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:
+
+```bash
+cp config.example.yaml config.yaml
+```
+
+2. Run a backup:
+
+```bash
+./docker-compose-backup backup -c config.yaml
+```
+
+3. List configured projects and existing backups:
+
+```bash
+./docker-compose-backup list -c config.yaml
+```
+
+4. Run as a daemon with cron scheduling:
+
+```bash
+./docker-compose-backup daemon -c config.yaml
+```
+
+## systemd deployment
+
+This repository includes `docker-compose-backup.service`, configured for installation under `/opt/docker-compose-backup`:
+
+```bash
+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](config.example.yaml) for a full annotated example.
+
+```yaml
+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)