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.
This commit is contained in:
2026-05-07 23:56:02 +01:00
parent ff8a5dbead
commit bb4ed3502d
47 changed files with 2818 additions and 61 deletions
+47 -5
View File
@@ -326,12 +326,54 @@ Sizes: **S** = under a day, **M** = 13 days, **L** = 37 days.
## Phase 5 — OSS readiness
- [ ] **P5-01** (M) Documentation site (mdBook or similar) with install, concepts, security model, screenshots
- [ ] **P5-02** (S) `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, issue + PR templates
- [x] **P5-01** (M) Documentation site (mdBook or similar) with install, concepts, security model, screenshots
- [x] **P5-02** (S) `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, issue + PR templates
- [x] **P5-03** (S) Release automation — **pivoted away from goreleaser/binary archives** on 2026-05-05 (spec: `docs/superpowers/specs/2026-05-05-p5-03-docker-only-release.md`). Single deliverable per tag: a multi-arch (linux amd64+arm64) server image, with cross-compiled agent binaries (linux amd64+arm64, windows amd64) + `install.sh` + `install.ps1` + the systemd unit baked under `/opt/restic-manager/dist/`. The `/agent/binary` and `/install/*` handlers fall back from `<DataDir>/...` to `<BundledAssetsDir>/...` so a fresh container Just Works. Workflow `.gitea/workflows/release.yml` triggers on `v*.*.*` tag-push (real release: fan-out `:vX.Y.Z`, `:X.Y`, `:X`, plus `:latest` once `MAJOR>=1`) and `workflow_dispatch` (snapshot: `:snapshot-<shortsha>` only). Pushed to the Gitea container registry on this instance — no external creds, no GHCR mirror. Cosign / SBOM / minisign / GHCR mirror deferred to Phase 6. Source builds via `make build` remain a first-class path.
- [ ] **P5-04** (S) Demo screenshots / short Loom walkthrough in README
- [ ] **P5-05** (S) `SECURITY.md` with disclosure process
- [ ] **P5-06** (M) End-to-end test suite in CI (Playwright vs. compose stack with sibling Linux agent)
- [x] **P5-04** (S) Demo screenshots / short Loom walkthrough in README
- [x] **P5-05** (S) `SECURITY.md` with disclosure process
- [x] **P5-06** (M) End-to-end test suite in CI (Playwright vs. compose stack with sibling Linux agent)
> **As shipped (2026-05-07, branch `p5-oss-readiness`):**
>
> **P5-01 — docs site.** mdBook under `docs/book/` with structured
> chapters: getting-started (install, enrolling hosts, reverse
> proxy), concepts (architecture, credentials, schedules + source
> groups, repo maintenance), operations (backups + restores, alerts,
> observability, updates), security (threat model, hardening,
> disclosure), reference (env vars, HTTP endpoints), plus
> contributing / roadmap / license pages. mdBook binary downloaded
> via Makefile (`make docs` / `make docs-watch`) — same "static
> binary, no toolchain" pattern as Tailwind. Generated `book/`
> dir gitignored.
>
> **P5-02 — CONTRIBUTING + CoC + templates.** `CONTRIBUTING.md`
> rewritten from placeholder to full guide (setup, conventions,
> workflow, RBAC of the project itself). `CODE_OF_CONDUCT.md`
> shaped on the Contributor Covenant but adapted for a
> single-maintainer project. `.gitea/issue_template/{bug_report,feature_request}.md`
> + `.gitea/PULL_REQUEST_TEMPLATE.md`.
>
> **P5-04 — README screenshots.** Six full-page captures from a
> fresh server bootstrap under `docs/screenshots/` (login, empty
> dashboard, add host, alerts, settings, audit log). README
> rewritten to centre the screenshot grid + link out to docs site.
> Captured live from a working build via Playwright; replaceable
> as the UI evolves without breaking layout.
>
> **P5-05 — SECURITY.md.** Disclosure policy (3-day ack, 30-day
> default disclosure window), supported-versions matrix, scope
> in/out, threat-model summary, hardening checklist for
> operators. Mirrored as a chapter in the docs site.
>
> **P5-06 — e2e harness.** `e2e/compose.e2e.yml` stands up
> server + sibling Linux agent (alpine + restic) + restic/rest-server
> backend, with announce-and-approve as the enrolment path so
> Playwright drives the operator flow end-to-end. Tests under
> `e2e/playwright/tests/`: smoke spec covers bootstrap → login →
> accept-pending → backup → terminal-status; second spec scrapes
> `/metrics` to verify the P6-04 endpoint. New
> `.gitea/workflows/e2e.yml` runs on every PR (separate from the
> fast lint/test workflow). Local how-to in `docs/e2e.md`.
- [x] **P5-07** (S) Reference deployment landed alongside P5-03. `deploy/docker-compose.yml` stands up *only* the server (image-pinned via `RM_VERSION`, named volume for operator state, bound to localhost) — TLS termination is left to whichever reverse proxy the operator already runs. `docs/reverse-proxy.md` documents the headers + WebSocket pass-through the proxy must forward, the `RM_TRUSTED_PROXY` CIDR rule, and worked examples for Caddy, nginx, and Traefik.
### Phase 5 acceptance