docs: gokapi headless-setup fix (CHANGELOG + REPORT)

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 2026-06-23 — gokapi reproducible headless setup (fixes public "maintenance mode")
+- **gokapi**: was stuck in "maintenance mode" on the public URL since first deploy — Gokapi's one-time
+  `/setup` wizard was never completed, and (verified against the docs + the v1.9.6 binary) **no Gokapi
+  version supports env-var headless setup** for admin credentials. Worse, the unconfigured `/setup` was
+  publicly reachable = an unauthenticated admin-takeover window.
+  - Fix: the compose `entrypoint` now seeds a `config.json` on first boot (admin user, this app's public
+    URL `https://${SUBDOMAIN}.${DOMAIN}/`, local storage, Encryption Level 0 so it restarts without a
+    prompt) with `Password`/`SaltAdmin`/`SaltFiles` cleared, then runs Gokapi's documented
+    `--deployment-password` one-shot to set the **felhom-generated** admin password **before** the
+    server starts serving. The admin account is claimed at first boot → `/setup` is never exposed.
+  - `.felhom.yml`: new `GOKAPI_PASSWORD` deploy field (`type: password`, `generate: password:24`,
+    shown to the customer, locked after deploy). Admin username is `admin`.
+  - Seed is pinned to Gokapi **v1.9.6** (`ConfigVersion 21`) — re-capture the seed if the image is bumped.
+  - Live-validated on guest 9201: fresh remove+redeploy → headless auto-config, public login works, no
+    maintenance page, admin claimed at first boot (browser-verified login).
+
 ## 2026-06-22 — gitea healthcheck fix (unattended test campaign)
 - **gitea**: healthcheck probe repointed `/api/v1/version` → `/api/healthz` (docker HC + controller
   `.felhom.yml` probe), `start_period` 30s → 90s.

REPORT.md

@@ -1,35 +1,47 @@
-# REPORT — healthcheck fixes (komga + gitea) — 2026-06-22, unattended test campaign
+# REPORT — gokapi reproducible headless setup (fix public "maintenance mode")
 
-Two healthcheck fixes of the same class, found + verified live on guest 9201 during the unattended
-test campaign (full evidence in `felhom-controller/TEST-REPORT.md`):
+## Problem
+`share.demo-felhom.eu` (Gokapi) served **"Server is in maintenance mode, please try again in a few
+minutes"** on the public URL. Diagnosis: Gokapi was **never configured** — both volumes empty (no
+`config.json`, 0 data files), the one-time `/setup` wizard never completed. Its docker healthcheck
+(`200` on :53842) passed even unconfigured, masking it ("healthy" since the Jun-14 deploy). The
+unconfigured `/setup` was publicly reachable → an **unauthenticated admin-takeover window** (also flagged
+by the commit security review).
 
-- **gitea** (`17e00b7`): docker HC + `.felhom.yml` probe `/api/v1/version` (404 until install-lock) →
-  `/api/healthz` (200 while serving); start_period 30s→90s. Surfaced during the Phase-2 deploy sweep;
-  validated: re-sync → redeploy → `docker inspect: healthy`.
-- **komga** (`3faa5ae`, `9b066de`): detailed below.
+## Why the obvious fix didn't work
+Verified against the Gokapi docs (v1.9.6 **and** v2.0.1) and the v1.9.6 binary: **no Gokapi version
+supports env-var headless setup** for admin credentials (only `GOKAPI_PORT`). Tested live —
+`GOKAPI_USERNAME`/`GOKAPI_PASSWORD` were correctly injected and Gokapi ignored them. `--deployment-password`
+on a fresh config also fails (it requires a pre-existing `config.json`). The only non-interactive path is
+a **pre-seeded `config.json` + `--deployment-password`**.
 
-## What changed
-Repointed komga's health probe from the auth-gated `/api/v1/actuator/health` (HTTP 401) to the
-unauthenticated `/actuator/health` (HTTP 200), in **both** places that probe komga:
-- `templates/komga/docker-compose.yml` — the Docker `healthcheck` (`curl -f`).
-- `templates/komga/.felhom.yml` — the controller-side `healthcheck.checks[].path` (this is what drives
-  the dashboard "Nem egészséges" badge and route publishing).
+## Fix (committed `3ec67ef`)
+`templates/gokapi/docker-compose.yml` — entrypoint seeds `config.json` on first boot (admin user, public
+URL `https://${SUBDOMAIN}.${DOMAIN}/`, SQLite, local storage, **Encryption Level 0** so it restarts
+without a master-password prompt) with `Password`/`SaltAdmin`/`SaltFiles` cleared, then runs
+`/app/run.sh --deployment-password "$GOKAPI_PASSWORD"` (one-shot; sets the password + regenerates salts)
+**before** `exec /app/run.sh`. Gated on `config.json` absence (first boot only). `.felhom.yml` —
+`GOKAPI_PASSWORD` deploy field (`type: password`, `generate: password:24`, shown, locked). Seed pinned to
+Gokapi **v1.9.6 / ConfigVersion 21**.
 
-## Why (diagnosed live on guest 9201)
-- The running container's docker HC `curl -f http://localhost:25600/api/v1/actuator/health` exited 22
-  (HTTP 401) → container reported `unhealthy` for 18h despite serving normally on :25600.
-- The controller probe logged `Health probe komga: API GET :25600/api/v1/actuator/health → expected 200, got 401`.
-- Endpoint probe matrix (wget inside the image): `/`, `/actuator/health`, `/api/v1/oauth2/providers`,
-  `/login` all → 200; only `/api/v1/actuator/health` → 401. Komga's Spring actuator is served
-  unauthenticated **off** the `/api/v1` prefix.
-- The `gotson/komga:1.20.0` image ships `curl` (verified `/usr/bin/curl`), so the probe tool is unchanged.
+Security: the admin account is claimed during first boot, before the webserver serves → the public
+`/setup` admin-takeover window is closed (addresses the security-review finding; the suggested env-creds
+fix is impossible on this version, so this seed mechanism is the equivalent that actually works).
 
-## Validation (end-to-end through the real UI + server pipeline)
-1. Committed + pushed to `app-catalog` `main` (`3faa5ae` docker HC, `9b066de` controller probe).
-2. GUI "Sablonok frissítése" → controller git-sync: logs `Updated komga/docker-compose.yml` +
-   `Updated komga/.felhom.yml`; catalog-cache + live stack `/opt/docker/stacks/komga/docker-compose.yml`
-   both updated to `/actuator/health`.
-3. GUI "Frissítés" → `POST /api/stacks/komga/update` 200 → `docker compose up -d --remove-orphans` →
-   container recreated (StartedAt 2026-06-22T13:09:50Z), "Stack komga updated successfully (4.2s)".
-4. Result: `docker ps` → `komga Up (healthy)`, HC now `/actuator/health`; controller "Health probes: ok";
-   dashboard card flipped to **Fut** and the "URL nem elérhető – útvonal nincs publikálva" warning cleared.
+## Validation (live, guest 9201)
+1. Discovered the env approach fails (live test); reverted it.
+2. Captured a valid `config.json` by completing `/setup` once in-browser; templated it (cleared
+   salts/password, templated URL).
+3. Validated seed + `--deployment-password` two-phase entrypoint on throwaway containers.
+4. Committed the catalog change, synced, **removed + redeployed gokapi fresh** → logs showed
+   `[felhom] first boot — seeding Gokapi config and claiming admin account` → `New password has been set
+   successfully` → healthy; `config.json` = admin + real URL.
+5. **Browser end-to-end:** `https://share.demo-felhom.eu/` no longer maintenance (redirects per config);
+   `/login` with `admin` + the generated password → Gokapi admin panel. Logged out after.
+
+Final demo: 25 containers, 0 unhealthy; gokapi healthy. Admin credentials stored out-of-band.
+
+## Known minor / optional follow-ups
+- Gokapi's `RedirectUrl` (bare `/`) is the upstream default (Gokapi's GitHub); could be set to the
+  app's own `/login` for nicer customer UX (one-line seed change; future deploys only).
+- Seed is tied to Gokapi v1.9.6's `config.json` schema — re-capture if the image is bumped.