48 lines
3.2 KiB
Markdown
48 lines
3.2 KiB
Markdown
# 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.
|