From 5ec658e0fac694d2722a2910ad6b7c47695f2435 Mon Sep 17 00:00:00 2001 From: atlas Date: Fri, 2 Oct 2026 13:23:09 +0200 Subject: [PATCH] docs(networking): drop remaining stale authelia-empty-user claims error-pages.nix paragraph (gateway.md:433) blamed a dead authelia upstream on an empty user set; the real reason the route earns a custom page is that a bare 502 there blames the proxy while the gateway itself is fine. gateway.md:38 dropped 'yet' from the placeholder-while-empty phrasing. services.md:109 corrected 'seeds an empty users database' to the disabled placeholder subject swarm-authelia.nix actually seeds (swarm-authelia.nix:873). Refs #3902 --- docs/networking/gateway.md | 6 +++--- docs/swarm/services.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/networking/gateway.md b/docs/networking/gateway.md index 802508f7..6d3588d2 100644 --- a/docs/networking/gateway.md +++ b/docs/networking/gateway.md @@ -35,7 +35,7 @@ The catch-all `_` vhost answers any other `Host` with `444` (connection closed, Only the host that **runs** authelia declares `auth.`; a hive that merely uses SSO knows `swarm.authelia.url` but doesn't answer for that name. The server name must be exactly `swarm.authelia.domain` — authelia checks that `authelia_url` sits inside its session cookie domain at startup, and refuses to boot otherwise. The vhost carries no Basic auth (that would put the login page behind the login it replaces) and passes `X-Forwarded-{Proto,Host,Uri,For}`, because authelia decides by the original request. -⚠️ `auth.` answering with the **sso unavailable** page means authelia isn't answering at all — check `journalctl -M swarm-authelia -u authelia-swarm`. A swarm with no real accounts yet boots fine (a disabled placeholder user keeps authelia's user store non-empty) and serves a login page that refuses everyone; add the first account with `swarmctl user add …` ([`setup.md`](../getting-started/setup.md)). +⚠️ `auth.` answering with the **sso unavailable** page means authelia isn't answering at all — check `journalctl -M swarm-authelia -u authelia-swarm`. While the user set is empty, a disabled placeholder user keeps authelia's user store non-empty, so it boots fine and serves a login page that refuses everyone; add the first account with `swarmctl user add …` ([`setup.md`](../getting-started/setup.md)). Per-agent UIs stay sub-path; forge and matrix get sub-domains → [Sub-domain shape](#sub-domain-shape-rationale). @@ -431,8 +431,8 @@ module reaches them through `gateway.lib.errorPages`. A route earns a custom page when the default status code would blame the wrong component. The per-agent routes qualify (a 502 there means the harness is restarting, not a gateway fault), and so does -`auth.` — a dead authelia upstream almost always means no users -yet, and a bare 502 blames the proxy, the one part that works. +`auth.` — a bare 502 there blames the proxy, but the gateway is +fine; authelia itself isn't answering. Forge, matrix and fluffychat keep nginx's defaults: a dead upstream there means what the status code says. diff --git a/docs/swarm/services.md b/docs/swarm/services.md index 01a7da65..b0dfdff8 100644 --- a/docs/swarm/services.md +++ b/docs/swarm/services.md @@ -106,7 +106,7 @@ there is one IdP and one auth path. Agent subjects come from swarm-controller's agent-creation job, written into the users database by `swarm-authelia-bridge`; human ones come from `swarmctl user add` → [setup.md § 2](../getting-started/setup.md#2--your-sso-account). -On first boot this module seeds an empty users database. Authelia generates session and storage keys in the container on +On first boot this module seeds the users database with a disabled placeholder subject, so authelia has a non-empty store to start against before any real account exists (`swarm-authelia.nix:873`). Authelia generates session and storage keys in the container on first boot and never rotates them automatically; replacing one invalidates data already written (sessions, the encrypted store), so that's an operator action.