Skip to content

About

Containerized service that propagates a homelab server's on-site backups to zero-touch offsite backup nodes over outbound HTTPS, with age encryption, minisign-signed manifests, and WORM storage.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

offsite-backup-manager

CI Release Go version License

⚠️ 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.

Why

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).

Images

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.

Quick start

  1. Generate an age identity + a minisign keypair using the Primary image itself (no local age/minisign install 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, and minisign.pub into the current directory and prints AGE_RECIPIENT=age1... for step 2. Store age-identity.txt somewhere safe (a password manager) and off the Primary — it's only needed later to decrypt backups (see docs/restore-runbook.md). minisign.key stays on the Primary (MINISIGN_SECKEY, passphrase as MINISIGN_PASSWORD); minisign.pub is copied to every node (MINISIGN_PUBKEY) to verify what it pulls. Omit -minisign-password for an unprotected key (not recommended).

  2. 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
  3. Mint a one-time enrollment token for your first node:

    docker exec backup-primary /app enroll-token -roster /data/roster.json
  4. 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.md for provisioning a dedicated device and docs/usage.md for every option.

Deployment

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: true

Admin 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.

Development

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.

AI-generated code

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 to main.
  • 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.

Contributing

See CONTRIBUTING.md for the branching model, commit conventions, and PR process. main is protected — all work flows through PRs.

License

Apache-2.0.

About

Containerized service that propagates a homelab server's on-site backups to zero-touch offsite backup nodes over outbound HTTPS, with age encryption, minisign-signed manifests, and WORM storage.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages