55 lines
3.7 KiB
Markdown
55 lines
3.7 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.
|
|
|
|
## Follow-ups applied
|
|
- Gokapi's `RedirectUrl` repointed from the upstream default (Gokapi's GitHub) → `https://${SUBDOMAIN}.${DOMAIN}/admin`,
|
|
so the bare root and the controller's "Megnyitás" link reach the Gokapi login instead of GitHub
|
|
(applied to live + seed; verified in-browser: `/` → `/admin` → login).
|
|
- `app_info.default_creds` added (shows admin username on the app-info page); `first_steps` updated for
|
|
the headless flow.
|
|
|
|
## Known minor / optional
|
|
- Seed is tied to Gokapi v1.9.6's `config.json` schema — re-capture if the image is bumped.
|
|
- The controller's "Megnyitás" link is always the bare subdomain root (no per-app path support); apps
|
|
whose UI isn't at `/` are handled by pointing their index redirect at the right path (as done here).
|