⚠️ AI-driven project. The majority of the code in this repository is generated by AI (GitHub Copilot) under human direction and review. Treat it accordingly: read the code, run the tests, and verify behaviour before relying on it. See AI-generated code for how this project is built.
A containerized service that propagates a homelab server's on-site backups to one
or more cheap, standalone, offsite backup nodes (e.g. a Raspberry Pi plugged in
at a remote site). The orchestrator compresses, encrypts, and signs the latest
backups into a single package per run; nodes pull that package over outbound
HTTPS and store it as write-once (WORM) data. See
docs/requirements.md for the full design, threat
model, and decisions.
Homelab backups are only as safe as their worst single-site failure. This project gets encrypted copies off-site with:
- Zero-touch nodes — a node boots, dials home, enrolls itself, and starts pulling. No interaction at the remote site, no inbound ports there.
- No external dependencies — just the Primary (behind your reverse proxy) and the nodes. No mesh/VPN coordinator, no third-party relay.
- Compromise-resistant — packages are encrypted to a public key whose private identity never lives on the server; nodes only ever hold ciphertext.
- WORM by construction — the Primary can never delete or modify node data (nodes pull; the Primary has no write path to them).
Published to GHCR, multi-arch (linux/amd64, linux/arm64, linux/arm/v7), with
an SBOM and signed build provenance. Every merge to main publishes :main and
:sha-<commit>; releases add :X.Y.Z, :X.Y, :X and :latest (releases up to
0.3.1 used :vX.Y.Z). Pin an exact version in production:
| Image | Default command | Does |
|---|---|---|
ghcr.io/scottfridwin/offsite-backup-manager-primary |
serve |
Serves the node-facing enroll/pull/heartbeat API; optionally self-schedules packaging runs. |
ghcr.io/scottfridwin/offsite-backup-manager-node |
run |
Enrolls once, then pulls and verifies new runs into an append-only store and reports a heartbeat. |
Both also expose admin subcommands (package, enroll-token, nodes,
retire-node, capacity, healthcheck) — see
docs/usage.md for the full CLI reference.
-
Generate an age identity + a minisign keypair using the Primary image itself (no local
age/minisigninstall needed):docker run --rm -v "$PWD":/out \ ghcr.io/scottfridwin/offsite-backup-manager-primary:latest \ keygen -out /out -minisign-password <your-passphrase>
This writes
age-identity.txt,minisign.key, andminisign.pubinto the current directory and printsAGE_RECIPIENT=age1...for step 2. Storeage-identity.txtsomewhere safe (a password manager) and off the Primary — it's only needed later to decrypt backups (seedocs/restore-runbook.md).minisign.keystays on the Primary (MINISIGN_SECKEY, passphrase asMINISIGN_PASSWORD);minisign.pubis copied to every node (MINISIGN_PUBKEY) to verify what it pulls. Omit-minisign-passwordfor an unprotected key (not recommended). -
Start the Primary (needs to be reachable over HTTPS for nodes to reach it — see Deployment for a proxied, hardened setup):
docker run -d --name backup-primary \ -v /srv/backups:/backups:ro \ -v ./minisign.key:/minisign.key:ro \ -v ./data:/data \ -e BACKUP_SOURCE_DIR=/backups \ -e PACKAGE_OUTPUT_DIR=/data/out \ -e NODE_ROSTER_FILE=/data/roster.json \ -e AGE_RECIPIENT=age1... \ -e MINISIGN_SECKEY=/minisign.key \ -p 8080:8080 \ ghcr.io/scottfridwin/offsite-backup-manager-primary:latest
-
Mint a one-time enrollment token for your first node:
docker exec backup-primary /app enroll-token -roster /data/roster.json -
Configure and start a node, pointed at the Primary with that token:
docker run -d --name backup-node \ -v ./store:/store \ -v ./minisign.pub:/minisign.pub:ro \ -e BACKUP_HOST=backup.example.com \ -e ENROLLMENT_TOKEN=<token-from-step-3> \ -e NODE_LABEL=pi-garage \ -e STORE_DIR=/store \ -e MINISIGN_PUBKEY=/minisign.pub \ ghcr.io/scottfridwin/offsite-backup-manager-node:latest
The node redeems the token once, then pulls, verifies, and heartbeats on its own — no further interaction needed. See
docs/node-setup.mdfor provisioning a dedicated device anddocs/usage.mdfor every option.
services:
backup-primary:
image: ghcr.io/scottfridwin/offsite-backup-manager-primary:latest
restart: unless-stopped
security_opt:
- "no-new-privileges=true"
cap_drop:
- ALL
read_only: true
tmpfs:
- /tmp
secrets:
- minisign_seckey
- minisign_password
environment:
- BACKUP_SOURCE_DIR=/backups
- PACKAGE_OUTPUT_DIR=/data/out
- NODE_ROSTER_FILE=/data/roster.json
- AGE_RECIPIENT=age1examplexxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
- MINISIGN_SECKEY=/run/secrets/minisign_seckey
- MINISIGN_PASSWORD_FILE=/run/secrets/minisign_password
- SCHEDULE=0 12 1 * * # monthly, midday; omit to trigger a run externally instead
volumes:
- /srv/backups:/backups:ro
- ./data/backup-primary:/data
networks:
- proxy
labels:
- "traefik.enable=true"
- "traefik.http.routers.backup.entrypoints=websecure"
- "traefik.http.routers.backup.rule=Host(`backup.example.com`)"
- "traefik.http.services.backup.loadbalancer.server.port=8080"
# Node routes authenticate with their own bearer token and must bypass
# any browser SSO/forward-auth your proxy applies to other services.
secrets:
minisign_seckey:
file: ./secrets/minisign.key
minisign_password:
file: ./secrets/minisign_password
networks:
proxy:
external: trueAdmin commands run as one-offs against the same service, e.g.
docker compose exec backup-primary /app nodes -roster /data/roster.json. See
docs/node-setup.md for the matching node-side compose
example (no inbound network needed — it only ever dials out) and
docs/usage.md for every command and environment variable.
Everything needed is in the dev container (.devcontainer/) — open the folder
in VS Code and "Reopen in Container". See CONTRIBUTING.md
for local checks, branching, and the release process, and
docs/usage.md for the full CLI reference.
This repository is an experiment in AI-driven development. Most code, docs, and configuration here are authored by AI (GitHub Copilot) with a human maintainer directing the work, reviewing every change, and merging via pull request. Practical implications:
- Every change lands through a reviewed PR with CI (see
CONTRIBUTING.md); nothing is pushed straight tomain. - Security-sensitive areas (crypto, auth, WORM guarantees) get extra human scrutiny;
see
SECURITY.md. - Contributions are welcome, but expect the AI-first workflow to continue.
See CONTRIBUTING.md for the branching model, commit
conventions, and PR process. main is protected — all work flows through PRs.