Initial baseline: home platform (k3s + Longhorn) specification repository

Greenfield spec set for a GitOps-driven PaaS+IaaS home platform: vision & requirements (R-* IDs), architecture, 14 domain specs, 11 ADRs, roadmap (phases + workstreams), and AI-agent coordination (roles, protocol, definition-of-done, task board). Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-08-15 22:37:56 -05:00
commit e8c555cfeb
@@ -0,0 +1,64 @@
+# 12 — Command & Control (C2) Center UI
+
+Serves: **R-C2-01/02**, surfaces **R-OBS-***, **R-GITOPS-***.
+
+## Purpose
+
+The root `home.keithjackson.dev` is the operator's front door: a single UI that shows what's running
+in the cluster, links to every service, and surfaces platform health and safe operational actions
+(R-C2-01/02).
+
+## Composition (assemble, don't reinvent)
+
+The C2 center is a curated composition of best-in-class UIs behind the root domain, not a bespoke
+app to build from scratch:
+
+- **Homepage (gethomepage.dev)** — the landing dashboard at the root: a live catalog of services
+  with links, status pings, and per-service widgets (many of the catalog services have native
+  Homepage widgets: Plex, Sonarr, Radarr, qBittorrent, PiHole, Gitea, etc.). This is the primary
+  R-C2-01 surface.
+- **Grafana** — embedded platform + per-service dashboards (R-OBS-03) for health at a glance.
+- **Headlamp** (or a comparable Kubernetes web UI) — a controlled Kubernetes console for viewing
+  workloads/VMs and performing scoped operational actions (restart, scale, inspect) — the R-C2-02
+  "controlled operational actions where safe" surface.
+- **Flux status** — GitOps reconciliation state (via Headlamp's Flux view, the Flux UI, or a
+  Homepage widget) so the operator sees drift/errors.
+- **Hubble UI** (optional) — network flow visualization for isolation troubleshooting.
+
+Each sub-UI is itself an onboarded, TLS-protected, access-controlled service; the root aggregates and
+links them. ADR-worthy only if a custom portal is later preferred over Homepage.
+
+## Data the C2 surfaces (R-C2-02)
+
+- **Service catalog**: every running service, its URL, its health, its egress class, its exposure.
+- **Platform health**: node status, Longhorn capacity/health, Flux reconciliation, cert expiry,
+  backup status, VPN tunnel state — sourced from the observability stack ([10](10-observability-and-alerting.md)).
+- **Alerts**: current firing alerts (mirrors what email delivers).
+
+## Actions (safe, audited)
+
+Operational actions exposed through the C2 must be **scoped and audited**, never a raw cluster-admin
+kubeconfig in a browser:
+- Restart/scale a workload, start/stop a KubeVirt VM, trigger a Flux reconcile, acknowledge an
+  alert.
+- Destructive actions (delete, offboard) require explicit confirmation and are logged.
+- Onboarding itself remains a **git PR** (GitOps), not a C2 button — the C2 may *link* to the
+  catalog/PR flow but does not bypass GitOps ([05](05-gitops-and-delivery.md)).
+
+## Access control
+
+- The C2 root and its sub-UIs are `internal` exposure by default (LAN-only) unless the operator
+  explicitly makes a component `public`.
+- Authentication in front of the C2 (and sensitive sub-UIs like Headlamp) — SSO/reverse-proxy auth —
+  is required; the mechanism (e.g. an identity-aware proxy) is pinned during the C2 workstream.
+- Trusted TLS on the root and all sub-UIs ([08](08-tls-and-certificates.md)).
+
+## Acceptance gates
+- `https://home.keithjackson.dev` serves the C2 landing UI over trusted TLS.
+- Every running service appears with a working link and live status.
+- Platform health (nodes, storage, Flux, certs, backups, VPN) is visible without leaving the C2.
+- Safe operational actions work and are access-controlled + audited; destructive actions confirm.
+
+## Open questions
+- Auth mechanism for the C2 (identity-aware proxy vs per-app auth) — pin in the C2 workstream.
+- Custom portal vs. Homepage-as-root long term (ADR if we diverge from Homepage).