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(3167): the setup guide gains a swarm UI step, and one group name

Browse source 
Per mara on the PR: the guide someone follows on a fresh deploy is a
different page from the one they read while debugging, and only the
second existed.

Also fixes a contradiction the request surfaced: setup.md and
swarm/sso.md have told every operator to create '--group admins' since
the bootstrap step existed, while the new rule required 'operators'.
This is the first rule that CONSUMES a group name, so it takes the one
the guide already creates - inventing a second would have meant every
account made by following the guide silently failing the check it was
supposed to pass, and for mara specifically a migration step that now
may not be needed at all.

setup.md's step 3 says why --group is not decoration; the new step 4
says what decides whether the page opens (the group, and the name
resolving) rather than listing a command, because there is nothing to
run. Steps renumbered, including the matrix block's internal 4a-4e.
This commit is contained in:
atlas 2026-08-12 17:57:52 +02:00
commit 4dd5093c6f
4 changed files with 51 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/swarm/README.md
View file

@ -97,7 +97,7 @@ another container, and the three ways that one gets delivered:
## Swarm UI
The operator-only web surface on the swarm apex, why reaching it needs
the `operators` group rather than just a session, and the four sites a
the `admins` group rather than just a session, and the four sites a
swarm service name has to be wired into: [`ui.md`](ui.md).
## The swarm's hive directory

19
docs/swarm/ui.md
View file

@ -25,21 +25,28 @@ way `swarm.forge.domain` and `swarm.matrix.gatewayHost` can.
> claiming one `server_name` do not error — nginx picks one — so this is
> an assertion rather than a runtime surprise.
## 🔑 You must be in the `operators` group
## 🔑 You must be in the `admins` group
**This is the step that separates "protected" from "locked out".** The
vhost's `auth_request` asks authelia *"is there a session"*; the rule
that makes it mean *"is this an operator"* is an `access_control` entry
requiring `group:operators`. An account without that group authenticates
requiring `group:admins`. An account without that group authenticates
fine and still gets bounced.
```sh
swarmctl user add <you> --group operators
swarmctl user add <you> --group admins
```
An account created before this existed has no groups. Re-add it with the
flag — `swarmctl` treats an existing entry as the canonical store, so the
group is what changes.
`admins` deliberately, not a new word: [`../setup.md`](../setup.md) has
told every operator to create exactly that group since the bootstrap step
existed, so an account made by following the guide already passes. This
is the first rule that *consumes* a group name — inventing a second one
would have meant those accounts silently failing a check they were
supposed to pass.
An account created without any group needs re-adding with the flag —
`swarmctl` treats the existing entry as the canonical store, so the group
is what changes.
Why a group and not a list of usernames: agents are getting authelia
accounts of their own (matrix SSO), and *authenticated* would then