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/setup.md b/docs/setup.md index a49ebb12..41050375 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -1,7 +1,8 @@ # First-run setup (fresh-deploy bootstrap) How to bring a fresh hyperhive hive online: provision accounts, open -the gateway, make matrix reachable, and spawn the first sub-agents. +the gateway, bootstrap swarm SSO, make matrix reachable, and spawn the +first sub-agents. Aimed at `ruth` (the root/manager agent) on a fresh deploy, but it's a plain reference doc — read it whenever you need the bootstrap command @@ -34,27 +35,44 @@ echo "hunter2" | hivectl gateway create-user mara --password-stdin hivectl gateway list-users ``` -### 3 · Matrix +### 3 · Swarm SSO (only when `swarm.authelia.enable`) + +⚠️ **Required to finish the install, not optional.** Authelia treats an +empty user store as a fatal startup error, so until this runs the +container crash-loops and `auth.` answers `502 Bad +Gateway` — a working vhost in front of an upstream that refuses to +start. Skipping this step looks like a broken proxy. ```bash -# 3a. Ensure the hive-internal admin account exists first +# Runs as root on the host that RUNS authelia (not necessarily the +# controller host). Prints a generated password once — record it. +swarmctl user add mara --display-name Mara --email mara@example.com --group admins +``` + +Detail, including what the password is and why this stays manual: +[`swarm/sso.md`](swarm/sso.md). + +### 4 · Matrix + +```bash +# 4a. Ensure the hive-internal admin account exists first hivectl matrix sync-admin -# 3b. Provision ruth's own matrix account +# 4b. Provision ruth's own matrix account hivectl matrix create-user ruth -# 3c. Create a human matrix account +# 4c. Create a human matrix account hivectl matrix create-user mara --password hunter2 -# 3d. Invite the operator to the hive Space (and optionally to rooms) +# 4d. Invite the operator to the hive Space (and optionally to rooms) hivectl matrix invite mara hivectl matrix invite @mara:yourserver --room '#hive-chat:yourserver' -# 3e. Promote the operator to homeserver admin if needed +# 4e. Promote the operator to homeserver admin if needed hivectl matrix promote-user mara ``` -### 4 · Spawn sub-agents +### 5 · Spawn sub-agents Sub-agent creation goes through the approval queue — ruth proposes, the operator approves, the container builds. From ruth's own turn (inside @@ -75,7 +93,7 @@ request_init_config(name: "iris") See [`approvals.md`](approvals.md) for the full flow. -### 5 · Useful host commands +### 6 · Useful host commands ```bash # Roster: all agents, status, rev, parent, pending reminders 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: