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)

Discovered the env approach fails (live test); reverted it.
Captured a valid config.json by completing /setup once in-browser; templated it (cleared salts/password, templated URL).
Validated seed + --deployment-password two-phase entrypoint on throwaway containers.
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.
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.

3.2 KiB Raw Blame History