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-07 23:56:02 +01:00
parent a252b25854
commit 89537d417a
47 changed files with 2818 additions and 61 deletions
@@ -0,0 +1,32 @@
+<!--
+Thanks for the PR! A few quick checks before submitting:
+
+* Did you open an issue first for non-trivial changes?
+* `make lint test` is green locally?
+* Commits are focused (one logical change per commit)?
+* No `Co-Authored-By` trailers (repo policy)?
+* No new dependencies without a one-line justification below?
+-->
+
+## Summary
+
+<!-- One paragraph: what changed and why. -->
+
+## Test plan
+
+<!-- Bullet list of what you actually ran. Be specific.
+     - `make test` → green
+     - Manually exercised the new flow at /hosts/{id}/foo
+     - Smoke env: enrolled a fresh host, ran a backup end-to-end
+-->
+
+## Notes for the reviewer
+
+<!-- Anything the reviewer needs to know that isn't obvious from the
+     diff: related issue, follow-up work that's intentionally not
+     in this PR, deferred concerns, design alternatives considered
+     and rejected. -->
+
+## Linked issues
+
+<!-- "Closes #123" / "Refs #456" / "Part of P5-06" -->
@@ -0,0 +1,52 @@
+---
+name: Bug report
+about: Something isn't behaving the way the docs / code suggest it should
+title: "[bug] "
+labels: bug
+---
+
+## What happened
+
+<!-- A clear description of the actual behaviour. Include the exact
+     UI surface, API endpoint, or CLI invocation involved. -->
+
+## What you expected
+
+<!-- What you thought would happen, and where that expectation came from
+     (docs page, command output, prior behaviour). -->
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Environment
+
+- restic-manager server version: <!-- `restic-manager-server --version` or footer of the UI -->
+- Agent version (if relevant): <!-- `restic-manager-agent --version` -->
+- restic version on affected host: <!-- `restic version` -->
+- Host OS: <!-- e.g. "Ubuntu 22.04 amd64" or "Windows Server 2022" -->
+- How was the server installed: <!-- docker compose / source build / other -->
+
+## Logs / output
+
+<details><summary>Server log (sanitised)</summary>
+
+```
+<!-- paste relevant lines; redact tokens, passwords, repo URLs -->
+```
+
+</details>
+
+<details><summary>Agent log (sanitised)</summary>
+
+```
+```
+
+</details>
+
+## Anything else
+
+<!-- Screenshots, related issues, recent changes you made before the
+     bug appeared, anything that might help. -->
@@ -0,0 +1,34 @@
+---
+name: Feature request
+about: Suggest a new capability or change to existing behaviour
+title: "[feature] "
+labels: enhancement
+---
+
+## What you're trying to do
+
+<!-- Describe the use case, not the proposed solution. Who is the
+     operator, what are they trying to accomplish, and what's
+     blocking them today? -->
+
+## Why the current behaviour falls short
+
+<!-- What does the system do today, and where does it stop short of
+     the use case above? -->
+
+## Proposed direction (optional)
+
+<!-- If you have a specific design in mind, describe it. Skip this
+     section if you'd rather leave it to the maintainer. -->
+
+## Scope check
+
+- [ ] I've read [`spec.md`](../spec.md) §2 (Goals & Non-Goals).
+- [ ] This isn't already on the roadmap in [`tasks.md`](../tasks.md).
+- [ ] This fits the project's "small fleet, one person operating"
+      target rather than enterprise / multi-tenant / SaaS use cases.
+
+## Anything else
+
+<!-- Related restic features, prior art in similar tools, links to
+     discussions you've had elsewhere. -->
@@ -0,0 +1,97 @@
+# P5-06 — End-to-end test suite.
+#
+# Spec : docs/superpowers/specs/2026-05-07-p5-oss-readiness-design.md
+# Stack: e2e/compose.e2e.yml (server + agent + rest-server)
+# Tests: e2e/playwright/tests/*.spec.ts
+#
+# Triggered on every PR into main and on workflow_dispatch. Runs
+# longer than the unit-test workflow (~3-4 minutes for a clean run);
+# kept separate so a slow e2e doesn't block the fast lint/test loop.
+
+name: e2e
+
+on:
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  e2e:
+    name: Playwright vs docker-compose
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build the e2e stack
+        run: docker compose -f e2e/compose.e2e.yml build
+
+      - name: Bring up the stack
+        run: docker compose -f e2e/compose.e2e.yml up -d server rest-server source-fixture
+
+      - name: Wait for server health
+        run: |
+          set -eu
+          for i in $(seq 1 30); do
+            if curl -fsS http://127.0.0.1:8080/api/version >/dev/null 2>&1; then
+              echo "server up"; exit 0
+            fi
+            sleep 2
+          done
+          echo "server didn't come up"; docker compose -f e2e/compose.e2e.yml logs server; exit 1
+
+      - name: Capture bootstrap token from server logs
+        id: bootstrap
+        run: |
+          set -eu
+          for i in $(seq 1 15); do
+            line=$(docker compose -f e2e/compose.e2e.yml logs server 2>&1 | grep -E 'bootstrap token' -A2 | grep -Eo '[a-zA-Z0-9_-]{40,}' | head -1 || true)
+            if [ -n "$line" ]; then
+              echo "RM_BOOTSTRAP_TOKEN=$line" >> "$GITHUB_ENV"
+              echo "got bootstrap token (${#line} chars)"
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "bootstrap token not found in logs"
+          docker compose -f e2e/compose.e2e.yml logs server
+          exit 1
+
+      - name: Start the agent
+        run: docker compose -f e2e/compose.e2e.yml up -d agent
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install Playwright
+        working-directory: e2e/playwright
+        run: |
+          npm install --no-audit --no-fund
+          npx playwright install --with-deps chromium
+
+      - name: Run Playwright tests
+        working-directory: e2e/playwright
+        env:
+          RM_BASE_URL: http://127.0.0.1:8080
+          RM_BOOTSTRAP_TOKEN: ${{ env.RM_BOOTSTRAP_TOKEN }}
+        run: npx playwright test
+
+      - name: Compose logs (on failure)
+        if: failure()
+        run: |
+          docker compose -f e2e/compose.e2e.yml logs --tail=200 server
+          docker compose -f e2e/compose.e2e.yml logs --tail=200 agent
+          docker compose -f e2e/compose.e2e.yml logs --tail=200 rest-server
+
+      - name: Upload Playwright report (on failure)
+        if: failure()
+        uses: actions/upload-artifact@v3
+        with:
+          name: playwright-report
+          path: e2e/playwright/playwright-report
+          retention-days: 7
+
+      - name: Tear down
+        if: always()
+        run: docker compose -f e2e/compose.e2e.yml down -v