From 014ae405e0360ee3edb542cb6869717404046965 Mon Sep 17 00:00:00 2001 From: atlas Date: Wed, 12 Aug 2026 00:31:07 +0200 Subject: [PATCH] docs(3186): the first user is required to start authelia, not to log in MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `swarm/sso.md` described the empty user store as a resting state — a provider that is reachable but has nobody in it yet. It isn't. Authelia validates the store at startup and treats zero users as fatal: error reading the authentication database: could not validate the schema: users: non zero value required so it exits 1, systemd restarts it, and an enabled-but-unbootstrapped swarm presents as a crash-looping container behind a vhost that is working correctly. The observed symptom is `502 Bad Gateway`, which reads as a proxy fault and is not one. Says so, gives the error text to grep for, and marks the `swarmctl user add` step as required to finish the install rather than as a first-login convenience. `gateway.md` gains the same warning next to the vhost, because that is where someone lands when the 502 is what they can see. The reason the store ships empty is unchanged and still right: seeding an account means a credential in a config file. What was wrong was calling the resulting state harmless. --- docs/gateway.md | 2 ++ docs/swarm/sso.md | 23 +++++++++++++++++++---- 2 files changed, 21 insertions(+), 4 deletions(-) diff --git a/docs/gateway.md b/docs/gateway.md index 4274892d..544296da 100644 --- a/docs/gateway.md +++ b/docs/gateway.md @@ -18,6 +18,8 @@ Single nginx in front of every hyperhive web surface. Runs on the **host**, next The authelia vhost is declared only by the host that **runs** authelia, not by every hive that uses it — a client hive knows the swarm's `authelia.url` but must not answer for a name it doesn't serve. Its server name is exactly `swarm.authelia.domain`: authelia validates `authelia_url ⊂ session cookie domain` at startup, so a near-miss is a container that refuses to boot. It carries no `auth_basic` — the login page must not sit behind the login mechanism it replaces — and sets the four `X-Forwarded-{Proto,Host,Uri,For}` headers, since authelia decides by the *original* request rather than the hop it sees. +⚠️ **A `502` from this vhost usually means authelia has no users yet, not that the proxy is misconfigured.** Authelia treats an empty user store as a fatal startup error, so an enabled-but-unbootstrapped swarm crash-loops the container while the vhost in front of it works perfectly. Check `journalctl -M swarm-authelia -u authelia-swarm` before suspecting anything here; the bootstrap step is in [`swarm/sso.md`](swarm/sso.md). + Per-agent UIs stay sub-path because they're hyperhive-internal and base-path-aware. External standard apps (forge / matrix) get sub-domains because their defaults work cleanly at sub-domain root + per-origin cookies / storage isolation matters. ## Discovery flow (matrix) diff --git a/docs/swarm/sso.md b/docs/swarm/sso.md index 627120c4..a0775860 100644 --- a/docs/swarm/sso.md +++ b/docs/swarm/sso.md @@ -18,10 +18,25 @@ name all follow `swarm.authelia.enable`, so there is nothing to turn on separately. (Details, including why a client hive must not declare that vhost: [`../gateway.md`](../gateway.md).) -Reachable is not the same as usable: the provider is generated with an -empty user set, deliberately. A provider with nobody in it yet is the -correct state for a fresh swarm — it is not a half-finished install, and -seeding a default account would be a credential in a config file. +**Authelia does not start until at least one user exists.** The user +store is generated empty — deliberately, since seeding a default account +would put a credential in a config file — but authelia validates it at +startup and treats "no users" as fatal: + +``` +error reading the authentication database: could not validate the schema: + users: non zero value required +``` + +It then exits 1 and systemd restarts it, so a swarm that has been +enabled but not bootstrapped shows a **crash-looping unit** and `502 Bad +Gateway` from the vhost — not a login page with nobody able to use it. +The gateway is working in that state; the upstream is not up. + +⚠️ So the step below is **required to finish the install**, not an +optional first-login convenience. Run it before concluding anything is +wrong with the proxy: a 502 here means "no users yet" far more often +than it means a routing fault. Add the first subject on the host running authelia: