From 4c0eb2f5d4f145439eeb539536e61694e0254ca9 Mon Sep 17 00:00:00 2001 From: kisfenyo Date: Sat, 13 Jun 2026 23:10:04 +0200 Subject: [PATCH] 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) --- documentation/REORG-NOTES-2026-06-13.md | 25 +++++++++++-------- .../architecture/05-hub-architecture.md | 8 +++--- .../controller/auth-hub-sync-integrations.md | 9 ++++++- .../controller/storage-monitoring-metrics.md | 9 +++++-- 4 files changed, 35 insertions(+), 16 deletions(-) diff --git a/documentation/REORG-NOTES-2026-06-13.md b/documentation/REORG-NOTES-2026-06-13.md index 05e7698..9c0fc30 100644 --- a/documentation/REORG-NOTES-2026-06-13.md +++ b/documentation/REORG-NOTES-2026-06-13.md @@ -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. diff --git a/documentation/architecture/05-hub-architecture.md b/documentation/architecture/05-hub-architecture.md index 61bb238..139dcf9 100644 --- a/documentation/architecture/05-hub-architecture.md +++ b/documentation/architecture/05-hub-architecture.md @@ -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 diff --git a/documentation/controller/auth-hub-sync-integrations.md b/documentation/controller/auth-hub-sync-integrations.md index 95db49c..7b4b760 100644 --- a/documentation/controller/auth-hub-sync-integrations.md +++ b/documentation/controller/auth-hub-sync-integrations.md @@ -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. diff --git a/documentation/controller/storage-monitoring-metrics.md b/documentation/controller/storage-monitoring-metrics.md index 1bc0ac8..7ecc1fc 100644 --- a/documentation/controller/storage-monitoring-metrics.md +++ b/documentation/controller/storage-monitoring-metrics.md @@ -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