147 lines
4.9 KiB
Markdown
147 lines
4.9 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```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
|
|
# 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 /opt/docker-compose-backup/docker-compose-backup.service
|
|
sudo ln -sf /opt/docker-compose-backup/docker-compose-backup.service /etc/systemd/system/docker-compose-backup.service
|
|
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](config.example.yaml) for a full annotated example.
|
|
|
|
```yaml
|
|
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.
|
|
|
|
## License
|
|
|
|
MIT. See [LICENSE](LICENSE).
|
|
|
|
`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)
|