Files

T

steve bb4ed3502d P5: OSS readiness — docs site, contributor onboarding, e2e harness

P5-01 — Documentation site under docs/book/ rendered with mdBook
(downloaded via Makefile, same static-binary pattern as Tailwind).
Structured chapters: getting started, concepts, operations,
security, reference. `make docs` / `make docs-watch`. Generated
output gitignored.

P5-02 — CONTRIBUTING.md rewritten from placeholder to a full
guide. CODE_OF_CONDUCT.md adapted from Contributor Covenant for a
single-maintainer project. .gitea/issue_template/{bug,feature}.md
and PULL_REQUEST_TEMPLATE.md.

P5-04 — Six README screenshots captured live from a fresh server
bootstrap (login, empty dashboard, add-host, alerts, settings,
audit log). README rewritten to centre the screenshot grid and
link out to the docs site.

P5-05 — SECURITY.md with disclosure policy (3-day ack, 30-day
default window), scope in/out, threat-model summary, operator
hardening checklist. Mirrored as a docs-site chapter.

P5-06 — End-to-end test harness. e2e/compose.e2e.yml brings up
server + sibling Linux agent (alpine + restic) + restic/rest-server.
Agent uses announce-and-approve so Playwright can drive the full
operator flow: bootstrap → login → accept pending → backup →
verify terminal status. Second spec scrapes /metrics to assert
the P6-04 endpoint surface. .gitea/workflows/e2e.yml runs on every
PR; local how-to in docs/e2e.md.

2026-05-08 20:08:23 +01:00

4.9 KiB

Raw Permalink Blame History

restic-manager

Self-hosted, browser-based, single-pane-of-glass for managing restic backups across a fleet of Linux and Windows endpoints.

Status: pre-1.0, feature-complete for the original use case. Phases 0–4 + 6 are landed (MVP, scheduling, restore, RBAC + OIDC, observability); Phase 5 (OSS readiness — docs site, contributor onboarding, end-to-end CI) is in flight. See spec.md for the design and tasks.md for the live roadmap.

What it does

Central visibility into backup state for every endpoint.
Trigger any restic operation remotely (backup, forget, prune, check, unlock, snapshots, stats, diff, restore).
Per-host schedules with named source groups + retention.
Live job log streamed to the browser; downloadable as text/NDJSON afterwards.
Restore wizard: browse a snapshot's tree, pick paths, restore in-place or to a new directory.
Repo health surfacing (size, raw size, last check, lock state), plus a 30/90-day repo-size trend.
Alerting over webhook, ntfy, or SMTP.
Cross-platform agent (Linux systemd + Windows SCM).
Append-only-friendly: separate admin credential for prune.
Optional Prometheus /metrics endpoint + sample Grafana dashboard.
Optional OIDC SSO (Authelia, Authentik, etc.).

Screenshots

Sign in	Empty dashboard	Add host

Alerts	Settings	Audit log

(Screenshots from a fresh smoke install with no hosts. A populated fleet view and the live-log + restore wizard surfaces are part of the docs site under docs/book/ — make docs to render locally.)

Architecture (one-line)

A small Go control-plane in Docker, lightweight Go agents on each endpoint holding an outbound WebSocket to the control-plane, and a restic repository (rest-server, S3, B2, SFTP — anything restic speaks) that holds the actual backup data. The control-plane never touches backup bytes.

Full architecture diagram and component breakdown: spec.md §3, or the rendered version in the docs site.

Repository layout

cmd/server/        control-plane binary
cmd/agent/         endpoint agent binary
internal/api       shared API types (REST + WS envelopes)
internal/server/   HTTP, WS, UI handlers, alert engine
internal/agent/    service integration, restic runner, local scheduler
internal/restic    restic CLI wrapper
internal/store     SQLite persistence
internal/crypto    secret encryption (AEAD)
internal/auth      passwords, sessions, agent tokens
web/               server-rendered templates + static assets
deploy/            Dockerfile, docker-compose.yml, install scripts, Grafana dashboard
docs/              prose docs + the mdBook site under docs/book
e2e/               compose stack + Playwright tests for end-to-end CI

Quickstart

The reference deployment is a single Docker container fronted by your existing reverse proxy. See the installation guide for the full path; the very short version:

export RM_VERSION=v0.9.0    # pin a real tag
export RM_BASE_URL=https://restic.example.com
export RM_TRUSTED_PROXY=10.0.0.0/8
docker compose -f deploy/docker-compose.yml up -d

The server prints a one-time bootstrap token to the log on first start. POST it to /api/bootstrap (or open /bootstrap in a browser) to create the admin user.

Local development

Requires Go 1.25+. The floor is set by modernc.org/sqlite v1.50.

make build           # builds cmd/server and cmd/agent into ./bin
make test            # runs go test ./...
make lint            # runs golangci-lint
make smoke-restart   # systemd --user smoke server (see CLAUDE.md)
make docs            # renders the mdBook site to docs/book/book/

End-to-end test harness against a Docker Compose stack with a sibling Linux agent: see docs/e2e.md. Runs in CI on every PR.

Documentation

Concepts and operator guides: docs site, rendered with make docs.
Reverse-proxy setup: docs/reverse-proxy.md.
Prometheus + Grafana: docs/prometheus.md.
End-to-end test harness: docs/e2e.md.
Security policy: SECURITY.md.
Contributing: CONTRIBUTING.md.

License

PolyForm Noncommercial 1.0.0. Free for personal, hobby, research, educational, governmental, and other noncommercial use. Commercial use requires a separate license.

4.9 KiB Raw Permalink Blame History Unescape Escape