KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #ai-agents #dsh-plugin #codex #developer-tools #claude-code #windows #desktop-app #typescript #rust #ai-agent #cli

stack-back

★ 178 Open GitHub ↗

Easy, automated, and incremental backups for any Docker Compose stack using restic.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![stack-back logo](https://raw.githubusercontent.com/lawndoc/stack-back/main/resources/stack-back_logo.svg)

[![docs](https://readthedocs.org/projects/stack-back/badge/?version=latest)](https://stack-back.readthedocs.io)

Automated incremental backups using [restic] for any docker-compose setup.

* Backup docker volumes or host binds
* Backup postgres, mariadb, and mysql databases
* Notifications over SMTP or Discord webhooks

# Usage

### Just add it to your services

```yaml
services:
  backup:
    image: ghcr.io/lawndoc/stack-back:<version>
    env_file:
      - stack-back.env
    environment:
      - AUTO_BACKUP_ALL: True
    volumes:
      - /var/run/docker.sock:/tmp/docker.sock:ro
      - cache:/cache # Persistent restic cache (greatly speeds up all restic operations)
```

### and it will back up all your volumes and databases

```yaml
  web:
    image: some_image  # Backs up the volumes below
    volumes:
      - media:/srv/media
      - /srv/files:/srv/files
  mysql:
    image: mysql:9  # Performs stateful backup using mysqldump
    volumes:
      - mysql:/var/lib/mysql  # Only SQL dump is backed up
```

[Documentation](https://stack-back.readthedocs.io)

Please report issus on [github](https://github.com/lawndoc/stack-back/issues).

## Configuration (environment variables)

Minimum configuration

```bash
RESTIC_REPOSITORY
RESTIC_PASSWORD
```

All config options can be found in the [template env file](./stack-back.env.template)

Restic-specific environment variables can be found in the [restic documentation](https://restic.readthedocs.io/en/stable/040_backup.html#environment-variables)

### Example config: S3 bucket

stack-back.env

```bash
AUTO_BACKUP_ALL=True
RESTIC_REPOSITORY=s3:s3.us-east-1.amazonaws.com/bucket_name
RESTIC_PASSWORD=thisdecryptsyourbackupsdontloseit
AWS_ACCESS_KEY_ID=<your access key id>
AWS_SECRET_ACCESS_KEY=<your access key id>
CHECK_WITH_CACHE=true
# snapshot prune rules
RESTIC_KEEP_DAILY=7
RESTIC_KEEP_WEEKLY=4
RESTIC_KEEP_MONTHLY=12
RESTIC_KEEP_YEARLY=3
# Cron schedule. Run every day at 1am
CRON_SCHEDULE="0 1 * * *"
```

## Advanced configuration (container labels)

You can also use `stack-back` container labels for granular control over which volumes get backed up.

```yaml
  web:
    image: some_image
    labels:
      - stack-back.volumes.exclude: files  # host mount substring matching
    volumes:
      - media:/srv/media       # will be backed up
      - /srv/files:/srv/files  # will NOT be backed up
  mysql:
    image: mysql:9
    labels:
      - stack-back.mysql: False   # don't perform database dump backup
      - stack-back.volumes: False # don't back up any volumes for this container either
    volumes:
      - mysql:/var/lib/mysql
```

Detailed documentation on compose labels can be found in the [stack-back documentation](https://stack-back.readthedocs.io/en/latest/guide/configuration.html#compose-labels)

## The `rcb` command

Everything is controlled using the [`rcb` command line tool](./src/) from this repo.

You can use the `rcb status` command to verify the configuration.

```bash
$ docker-compose exec -it backup rcb status
INFO: Status for compose project 'myproject'
INFO: Repository: '<restic repository>'
INFO: Backup currently running?: False
INFO: --------------- Detected Config ---------------
INFO: service: mysql
INFO:  - mysql (is_ready=True)
INFO: service: mariadb
INFO:  - mariadb (is_ready=True)
INFO: service: postgres
INFO:  - postgres (is_ready=True)
INFO: service: web
INFO:  - volume: media
INFO:  - volume: /srv/files
```

The `status` subcommand lists what will be backed up and even pings the database services checking their availability.

More `rcb` commands can be found in the [documentation].

# Contributing

Contributions are welcome regardless of experience level.

## Python environment

Use [`uv`](https://docs.astral.sh/uv/) within the repo root directory to manage your development environment.

```bash
git clone https://github.com/lawndoc/stack-back.git
cd stack-back
uv sync --directory src/
```

## Running unit tests

Make sure `uv` is already set up as shown above.

```bash
# Run only unit tests (fast)
uv run --directory src/ pytest -m unit

# Run only integration tests
uv run --directory src/ pytest -m integration

# Run all tests (unit + integration)
uv run --directory src/ pytest
```

**Note:** Integration tests require Docker and docker compose plugin, and will spin up real database containers. They take significantly longer than unit tests.

## Building Docs

```bash
pip install -r docs/requirements.txt
python src/setup.py build_sphinx
```

[restic]: https://restic.net/
[documentation]: https://stack-back.readthedocs.io

---
This project is an actively maintained fork of [restic-compose-backup](https://github.com/ZettaIO/restic-compose-backup) by [Zetta.IO](https://www.zetta.io).

Huge thanks to them for creating this project.

[![Zetta.IO](https://raw.githubusercontent.com/lawndoc/stack-back/main/.github/logo.png)](https://www.zetta.io)

stack-back

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README