diff --git a/docs/gateway.md b/docs/gateway.md index 544296da..4274892d 100644 --- a/docs/gateway.md +++ b/docs/gateway.md @@ -18,8 +18,6 @@ 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 41050375..a49ebb12 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -1,8 +1,7 @@ # First-run setup (fresh-deploy bootstrap) How to bring a fresh hyperhive hive online: provision accounts, open -the gateway, bootstrap swarm SSO, make matrix reachable, and spawn the -first sub-agents. +the gateway, 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 @@ -35,44 +34,27 @@ echo "hunter2" | hivectl gateway create-user mara --password-stdin hivectl gateway list-users ``` -### 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. +### 3 · Matrix ```bash -# 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 +# 3a. Ensure the hive-internal admin account exists first hivectl matrix sync-admin -# 4b. Provision ruth's own matrix account +# 3b. Provision ruth's own matrix account hivectl matrix create-user ruth -# 4c. Create a human matrix account +# 3c. Create a human matrix account hivectl matrix create-user mara --password hunter2 -# 4d. Invite the operator to the hive Space (and optionally to rooms) +# 3d. Invite the operator to the hive Space (and optionally to rooms) hivectl matrix invite mara hivectl matrix invite @mara:yourserver --room '#hive-chat:yourserver' -# 4e. Promote the operator to homeserver admin if needed +# 3e. Promote the operator to homeserver admin if needed hivectl matrix promote-user mara ``` -### 5 · Spawn sub-agents +### 4 · 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 @@ -93,7 +75,7 @@ request_init_config(name: "iris") See [`approvals.md`](approvals.md) for the full flow. -### 6 · Useful host commands +### 5 · 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 a0775860..627120c4 100644 --- a/docs/swarm/sso.md +++ b/docs/swarm/sso.md @@ -18,25 +18,10 @@ 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).) -**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. +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. Add the first subject on the host running authelia: