Service Backup Agent

Modular Docker-based backup system for self-hosted services, with a web GUI.

Quick Start

cp .env.example .env
chmod 600 .env
# Fill in .env with your real values

chmod 700 backups logs state

docker compose build
docker compose up -d
docker logs -f service-backup-agent

Open the GUI at http://localhost:8080

How It Works

Each service has a worker that talks to that service's own REST/GraphQL API (or, for Vaultwarden, its official CLI) — never the underlying database directly. There are no database dumps, no docker exec into other containers, and no DB credentials anywhere in this project. A worker only ever gets what that service's own API is willing to hand back to an authenticated client, written out as JSON/Markdown and archived into a tar.gz (or left as a single JSON file for small exports).

A scheduler runs each enabled worker on a cron-like schedule, writes the result to state/{service}/last_result.json, and optionally uploads the output to a configured destination (currently Google Drive).

See architecture.md for the full data flow, API surface, and design decisions.

Supported Services

Destination: Google Drive — uploads every successful backup after it's written locally.

Adding a New Service

1. Create app/workers/<name>.py inheriting BackupWorker
2. Set worker_type, display_name, description, env_var_specs
3. Implement run(context: BackupContext) -> BackupResult
4. Register in app/core/registry.py → create_default_registry()
5. Add entry to config/services.json
6. Add a setup guide under docs/services/

The GUI loads worker metadata dynamically — no GUI changes needed.

Security

The web GUI has no built-in authentication — put it behind an auth proxy (nginx + basic auth, Authelia, Traefik forward auth) for any remote access. See security.md for the full threat model and secret-handling details.

Check Backups

ls -lh backups/vaultwarden/
ls -lh backups/wikijs/

Development

Run Tests

pip install -r requirements.txt
pytest -v

Lint and Format

pip install ruff
ruff check app/ tests/
ruff format app/ tests/

Reproducible Builds

requirements.txt is a fully pinned lock file generated by pip-tools. requirements.in contains the human-readable version constraints.

To regenerate the lock file after updating requirements.in:

pip install pip-tools
pip-compile requirements.in -o requirements.txt

The Bitwarden CLI version is pinned via the BW_CLI_VERSION build arg in the Dockerfile. To update it: edit the ARG BW_CLI_VERSION=... line, then rebuild.