docs: close doc-gaps (hub v0.11.0, onlyoffice:nextcloud occ internals, metricsDBPath verified)

- 05-hub-architecture.md: stale 'felhom-hub v0.6.3' -> v0.11.0 (design-draft note). - auth-hub-sync-integrations.md: full onlyoffice:nextcloud occ command sequence. - storage-monitoring-metrics.md: metricsDBPath verified to coincide with the volume-backed data_dir on the bootstrap guest (persists; hardcoding is latent fragility only). - REORG-NOTES: gaps 2/3 CLOSED, gap 5 partially closed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-13 23:10:04 +02:00
parent 280781115d
commit 4c0eb2f5d4
4 changed files with 35 additions and 16 deletions
@@ -86,18 +86,23 @@ anchors):
   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.
+2. **`metricsDBPath` — CLOSED (2026-06-13).** Verified on the live bootstrap-managed guest 9201: the
+   `felhom-controller-data` volume mounts at `/opt/docker/felhom-controller`, `data_dir` =
+   `/opt/docker/felhom-controller/data`, and `metrics.db` lives there — so the hardcoded
+   `metricsDBPath` (`main.go:189`) **coincides** with the volume-backed `data_dir` and metrics persist
+   correctly. Residual (low-priority backlog, not a live bug): the path is hardcoded rather than derived
+   from `cfg.Paths.DataDir`, so it would diverge if `data_dir` were ever reconfigured. Documented in the
+   storage doc.
+3. **`onlyoffice:nextcloud` internals — CLOSED (2026-06-13).** Read `internal/integrations/onlyoffice_nextcloud.go`;
+   documented the full `occ` command sequence (install/enable + DocumentServerUrl/InternalUrl/jwt_secret/
+   StorageUrl + trusted_domains; `Revoke` = `app:disable`) in `auth-hub-sync-integrations.md`.
 4. **`selfUpdateAuthMiddleware`** (API auth wrapper for the hub-callback `/api/selfupdate|config|geo`
-   routes) referenced but its implementation not read in depth.
+   routes) referenced but its implementation not read in depth. (Still open.)
 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.
+   *design drafts*. PARTIALLY CLOSED: `05-hub-architecture.md`'s stale "felhom-hub v0.6.3" corrected to
+   v0.11.0 (with a design-draft note). `01,03,04` + `proxmox-platform.md` still reference older precedent
+   and remain design-drafts — full grounding against agent v0.30.0 / hub v0.11.0 is the recommended next
+   docs slice (the top index already records current versions).
 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.

@@ -4,9 +4,11 @@
 > felhom-hub source** (`felhom.eu` repo, `hub/`) + Parts 01–04, then placed at
 > `docs/architecture/05-hub-architecture.md`.
 >
-> The hub is **not** greenfield — it's a mature service (felhom-hub v0.6.3, Go + SQLite on k3s,
-> `hub.felhom.eu`). This doc is the **deltas** to evolve it for the Proxmox model, plus the new
-> data model. Builds on Part 1 (trust/enrollment), Part 3 (the agent + reconcile), Part 4 (signing).
+> The hub is **not** greenfield — it's a mature service (felhom-hub **v0.11.0** as of 2026-06-13, Go +
+> SQLite on k3s, `hub.felhom.eu`). This doc is the **deltas** to evolve it for the Proxmox model, plus
+> the new data model. Builds on Part 1 (trust/enrollment), Part 3 (the agent + reconcile), Part 4 (signing).
+> NOTE: this remains a design-draft for the deltas; the live hub is v0.11.0 (the prior "v0.6.3" reference
+> was stale). Ground specifics against `felhom.eu/hub/` before relying on them.

 ## 1. Source-of-truth model — two drivers, two directions

@@ -73,7 +73,14 @@ Lets one app configure another (e.g. enable OnlyOffice editing inside FileBrowse

 **Concrete handlers (registered in `NewManager`):**
 - `onlyoffice:filebrowser` — `Apply` reads OnlyOffice's `JWT_SECRET` and subdomain from the provider's decrypted `app.yaml` env, then patches FileBrowser's `config.yaml` with an `integrations.office` block (public office URL, internal `http://onlyoffice:80`, the shared JWT secret) and restarts FileBrowser. `Revoke` strips that block and restarts. Writes are atomic (tmp+rename). FileBrowser is treated as always-present infrastructure (not gated on "deployed").
- `onlyoffice:nextcloud` — patches Nextcloud via occ commands (separate handler).
+- `onlyoffice:nextcloud` — `Apply` (`internal/integrations/onlyoffice_nextcloud.go`) drives Nextcloud's
+  OnlyOffice connector entirely through `docker exec -u www-data nextcloud php occ` commands, in order:
+  `app:install onlyoffice` → `app:enable onlyoffice` → `config:app:set onlyoffice DocumentServerUrl`
+  (public office URL) / `DocumentServerInternalUrl` (`http://onlyoffice:80`) / `jwt_secret` (the shared
+  JWT secret read from OnlyOffice's env) / `StorageUrl` (`http://nextcloud/`) → `config:system:set
+  trusted_domains 10 nextcloud`. Each `occ` call runs under a context timeout; a failure aborts and is
+  surfaced (Hungarian error). `Revoke` runs `occ app:disable onlyoffice` (a not-installed result is
+  treated as already-revoked). No config-file patching — Nextcloud owns its own state via `occ`.

 **Lifecycle hooks.** `Toggle` validates that provider (and target, unless it's filebrowser) are deployed and running before applying. The manager exposes:
 - `OnStackStop` — revokes active integrations where the stack is provider or target, but keeps `enabled=true` and marks status `provider_stopped`/`target_unavailable` so they can come back.
@@ -178,8 +178,13 @@ the storage-management page via the agent host-metrics view).

 ### SQLite store (`store.go`)

-`NewMetricsStore(dbPath)` opens `modernc.org/sqlite` at
-`/opt/docker/felhom-controller/data/metrics.db` and **verifies WAL mode took effect** — it
+`NewMetricsStore(dbPath)` opens `modernc.org/sqlite` at `metricsDBPath`, hardcoded in `main.go:189` to
+`/opt/docker/felhom-controller/data/metrics.db`. On the live bootstrap-managed guest this **coincides
+with the volume-backed `data_dir`** (the `felhom-controller-data` volume mounts at
+`/opt/docker/felhom-controller`; `data_dir: /opt/docker/felhom-controller/data`), so metrics persist
+across restarts. The path is hardcoded rather than derived from `cfg.Paths.DataDir` — a latent fragility
+(would diverge if `data_dir` were reconfigured), tracked as a low-priority backlog item, not a live bug.
+The store **verifies WAL mode took effect** — it
 errors out if `PRAGMA journal_mode=WAL` does not return `"wal"` (`store.go:27-34`), then sets
 `synchronous=NORMAL` and `busy_timeout=5000`. Two tables: `system_metrics` and
 `container_metrics`, with ts indices (`:48-77`). Queries downsample into time buckets