# REPORT — gokapi reproducible headless setup (fix public "maintenance mode")

## 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).

## 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`**.

## 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**.

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 (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.