110 lines
7.5 KiB
Markdown
110 lines
7.5 KiB
Markdown
# Documentation reorg + refresh — 2026-06-13
|
|
|
|
Rationale, inventory of changes, what was verified, and the doc-gaps left for review. Part of the
|
|
audit-fix + docs-centralize session (controller v0.59.0; agent v0.29.1; hub v0.11.0).
|
|
|
|
## Goal
|
|
|
|
Give the **controller** a documentation home under `felhom.eu/documentation/` as thorough as the
|
|
agent/platform/hub already have, and ground everything in **current code** (not memory or stale
|
|
repo-local docs — the controller's own `controller/README.md` banner referenced v0.45 while live was
|
|
v0.58). Centralize so there is one published-docs home; keep per-repo operational working files in their
|
|
repos.
|
|
|
|
## Structure chosen (and why)
|
|
|
|
```
|
|
documentation/
|
|
README.md # NEW — top-level index across controller/agent/platform/hub/audits/tests
|
|
controller/ # NEW subtree — the controller, mirroring the agent's depth
|
|
README.md # controller docs index + overview
|
|
module-map.md # current per-package map (supersedes architecture/02 planning map)
|
|
deploy-and-stack-lifecycle.md
|
|
backup-architecture.md
|
|
storage-monitoring-metrics.md
|
|
auth-hub-sync-integrations.md
|
|
audits/ # NEW — authoritative remediation record
|
|
deep-sweep-2026-06-13.md # (from controller audit/2026-06-13-deep-sweep, + status header)
|
|
bughunt-reconcile-2026-06-13.md
|
|
architecture/ 01..05, _reviews # unchanged (agent/platform/hub design docs)
|
|
proxmox-platform.md # unchanged
|
|
tests/ # unchanged (spike findings)
|
|
```
|
|
|
|
Why this shape: the agent/platform/hub already live under `architecture/` as numbered design docs; the
|
|
controller had **no** central home (its prose lived in the repo README, stale). Rather than renumber the
|
|
existing set, I added a sibling `controller/` subtree (feature-doc style, like the agent's areas) and a
|
|
top-level `README.md` index that ties all four components together. The four controller feature docs are
|
|
split by **area** (deploy, backup, storage/monitoring, auth/hub-glue) so each maps to a coherent set of
|
|
packages and can be maintained independently.
|
|
|
|
## What was created / changed
|
|
|
|
- **Created** `documentation/README.md` (top index), `documentation/controller/` (5 files),
|
|
`documentation/audits/` (2 records). All additive.
|
|
- **Superseded, not deleted:** `architecture/02-controller-module-map.md` (v0.33 planning map) is kept
|
|
for history; `controller/module-map.md` is the live map and links back to it. Used additive
|
|
cross-links rather than `git mv` because the old doc is a *planning* artifact with distinct value
|
|
(the KEEP/PORT/DELETE rationale), not a stale copy of the new one.
|
|
- **`controller/README.md` (controller repo):** an authoritative banner was prepended — version bumped to
|
|
v0.59.0, a "documentation has moved" pointer to `documentation/controller/`, the bootstrap-managed
|
|
deploy note, and a marker that the body is retained legacy reference. The 1987-line body was NOT
|
|
rewritten this session (safety over completeness — a full unattended rewrite risked garbling
|
|
operational/build detail). Fully slimming the body to a pure quickstart is a deferred follow-up; until
|
|
then the banner makes the central docs authoritative and warns the body may lag.
|
|
- **`BUGHUNT.md` (controller repo):** added a reconciliation banner (H10 fixed, pointer to the
|
|
reconcile record); original content preserved.
|
|
- **`CONTEXT.md` (controller repo):** banner-and-below refreshed to v0.59.0 state.
|
|
- **Removed** the accidental committed artifact `controller/mnt/user-data/outputs/felhom-controller/`
|
|
(a stale duplicate of the README under a Claude-sandbox output path; see "Tidy" below).
|
|
|
|
## What each major controller claim was verified against
|
|
|
|
Each of the four feature docs was drafted by reading the **actual current source** and carries an inline
|
|
content grounded in these packages (the drafting captured a per-doc verification ledger; representative
|
|
anchors):
|
|
- **deploy-and-stack-lifecycle:** `internal/stacks/deploy.go` (AppConfig:98, H1 check-and-set:122-139,
|
|
CTRL-T2-1 transitional `deployed:false`:~295-336 + success flip in `runComposeDeploy`, H10 fail-closed
|
|
in `SaveAppConfig`), `manager.go` (Stack/ContainerState, up-d-not-restart), `delete.go` (H2 guards,
|
|
protected enforcement), `infra.go` (`EnsureBaseStack` TryLock + filebrowser-preserve), `healthprobe.go`.
|
|
- **backup-architecture:** `internal/appbackup/dbdump.go` (docker-ps discovery, H8 Sync+Close-before-
|
|
rename), `paths.go`/`backup.go` (`GetAppDrivePath` systemDataPath fallback — C3 moot), `recovery_unit.go`
|
|
(secret-free unit), `restore_unit.go` (fail-closed data-key gate), `tier2.go` (off-drive rsync +
|
|
rootfs-headroom guard), `quiesce/quiesce.go`, `agentapi/client.go` (whole-guest backup is the agent's).
|
|
- **storage-monitoring-metrics:** `internal/agentapi/client.go` (DiskInfo, leaf-pin), `web/agent_disk_handlers.go`
|
|
+ `storage_handlers.go` (thin proxies, 409 on agent refusal), `system/dockervol.go` (reserve floor
|
|
max(5GB,10%), HTTP 507 deploy gate), `metrics/store.go` (WAL verified), `metrics/collector.go`
|
|
(cancellable ctx), `monitor/healthcheck.go` (watchdog/pinger gone).
|
|
- **auth-hub-sync-integrations:** `web/auth.go`+`csrf.go` (bcrypt, cookie flags, demo open-mode, XFF
|
|
rate-limit), `setup/`+`bootstrap/` (NeedsSetup, bootstrap.json v2), `report/`+`notify/` (zero-knowledge
|
|
hub push), `sync/sync.go` (never overwrites app.yaml), `integrations/`, `cloudflare/waf.go`
|
|
(`[felhom-geo]`), `selfupdate/updater.go` (pinned tags, never `:latest`), `assets/syncer.go`.
|
|
|
|
## Doc-gaps / uncertainties left for review (per the cardinal rule — flagged, not guessed)
|
|
|
|
1. **Daily volume-dump consistency:** `DumpAppVolumesSafe` (stop→dump→restart) exists, but whether the
|
|
daily scheduled path calls it or the unsafe `DumpAppVolumes`, and the exact volume-tar trigger on the
|
|
daily cadence, was not fully traced from `main.go`. Backup doc describes volume tars without asserting
|
|
live-dump consistency. (Trace `cmd/controller/main.go` schedule wiring next.)
|
|
2. **`metricsDBPath` hardcoded** to `/opt/docker/felhom-controller/data/metrics.db` in `main.go` even on
|
|
the bootstrap-managed guest (no compose). Documented as-is; whether that path is correct under the
|
|
golden/bootstrap data volume was not assessed.
|
|
3. **`onlyoffice:nextcloud` integration internals** not opened (only confirmed registered + occ-based);
|
|
documented at one-line depth.
|
|
4. **`selfUpdateAuthMiddleware`** (API auth wrapper for the hub-callback `/api/selfupdate|config|geo`
|
|
routes) referenced but its implementation not read in depth.
|
|
5. **Agent/platform/hub design docs (`architecture/01,03,04,05`, `proxmox-platform.md`)** are explicit
|
|
*design drafts*. I did NOT rewrite them — a half-verified refresh risks regressing decision content.
|
|
Known drift to fix in a dedicated pass: `05-hub-architecture.md` prose still says "felhom-hub v0.6.3"
|
|
(live is v0.11.0); `02`/`03` reference v0.33 controller precedent. The top index records the current
|
|
versions; full grounding of these against agent v0.29.1 / hub v0.11.0 is the recommended next docs slice.
|
|
6. **Front-end (templates) deploy progress markup** lives in `web/templates`, documented only via the
|
|
in-memory state it polls, not the template/endpoint markup.
|
|
|
|
## Tidy
|
|
|
|
- `controller/mnt/user-data/outputs/felhom-controller/{README.md,assets/README.md}` was a tracked
|
|
accidental commit (a stale 283-line duplicate README under a Claude sandbox output path, from the
|
|
initial `added controller` commit). Removed via `git rm` — clearly safe (stale duplicate, obviously
|
|
accidental path). Noted here for the record.
|