vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(3186): the setup walkthrough gains the swarm SSO bootstrap

Browse source 
`setup.md` is the page someone follows on a fresh deploy, and it had no
step for authelia at all — so the operator finished the walkthrough with
a crash-looping container and a 502, having done everything the doc
asked. The warnings added to sso.md and gateway.md only help someone who
is already debugging; this is the page that decides whether they end up
debugging.

New step 3, gated on `swarm.authelia.enable`, placed before matrix
because it is part of getting the front door open. Says plainly that it
is required to finish the install, names the symptom it prevents, and
links sso.md for the detail rather than restating it.

Renumbers matrix (4), spawn (5) and host commands (6), including the
matrix block's own 3a–3e labels, which would otherwise disagree with
their heading.
This commit is contained in:
atlas 2026-08-12 10:06:37 +02:00
commit a2ea91afe2
1 changed files with 27 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

36
docs/setup.md
View file

@ -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.<swarm.domain>` 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