steve
bb4ed3502d
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.
127 lines
4.9 KiB
Markdown
127 lines
4.9 KiB
Markdown
# restic-manager
|
||
|
||
Self-hosted, browser-based, single-pane-of-glass for managing
|
||
[restic](https://restic.net) 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`](./spec.md) for the design and [`tasks.md`](./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/`](./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](./spec.md), or the rendered version in the
|
||
[docs site](./docs/book/src/concepts/architecture.md).
|
||
|
||
## 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](docs/book/src/getting-started/install.md)
|
||
for the full path; the very short version:
|
||
|
||
```sh
|
||
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.
|
||
|
||
```sh
|
||
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`](docs/e2e.md). Runs in CI
|
||
on every PR.
|
||
|
||
## Documentation
|
||
|
||
- **Concepts and operator guides**: [docs site](docs/book/src/intro.md),
|
||
rendered with `make docs`.
|
||
- **Reverse-proxy setup**: [docs/reverse-proxy.md](docs/reverse-proxy.md).
|
||
- **Prometheus + Grafana**: [docs/prometheus.md](docs/prometheus.md).
|
||
- **End-to-end test harness**: [docs/e2e.md](docs/e2e.md).
|
||
- **Security policy**: [SECURITY.md](SECURITY.md).
|
||
- **Contributing**: [CONTRIBUTING.md](CONTRIBUTING.md).
|
||
|
||
## License
|
||
|
||
[PolyForm Noncommercial 1.0.0](./LICENSE). Free for personal,
|
||
hobby, research, educational, governmental, and other noncommercial
|
||
use. Commercial use requires a separate license.
|