docs(swarm): facts + structure pass
swarm/README.md opens with the swarm and its control plane; hive identity and the directory follow as the substrate. Upgrade notes move into a <details> block, the per-agent queue publishing detail into another, and the one-paragraph pointer sections collapse into a link list. Fact fixes, checked against origin/main: - an empty swarm.hives fails eval (swarm.nix:341-354); it does not mean "not in a swarm" - swarm.domain is required with a hive (hive-network.nix:156,188), hiveName with a hive, store or homeserver (hyperhive.nix:161-166) - the matrix container trusts the hive's trust-bundle.pem at runtime under self-signed certs (hive-matrix.nix:1046-1052, lib/hive-ca-trust.nix:76-85) - singleHostSwarm also defaults the controller, localHostsEntry, the nats callout keys and the bao bootstrap token path (local-defaults.nix:72-129) - swarm-controller serves far more than /health: roster, wanted state, job graph, agent creation and credential mints (main.rs:2874-2899) - swarmctl user add needs --email for the forge account and refuses an existing user (setup.md:67-71, swarmctl/src/main.rs:425-430); document agent mint-identity and mint-forge-token - agent creation also mints store identity, forge token and matrix account, and declares the agent paused (main.rs:1822-1920, 247-248) Refs #3902
This commit is contained in:
atlas
mara
parent
f688cfcdf0
commit
270430a4b4
5 changed files with 408 additions and 402 deletions
|
|
@ -1,10 +1,23 @@
|
|||
# Swarm UI
|
||||
|
||||
The swarm's own web surface, served by the gateway on the **swarm apex**
|
||||
(`services.hyperhive.swarm.domain`) and readable only by operators.
|
||||
The swarm's own web surface and the operator's day-to-day view: served by
|
||||
the gateway on the **swarm apex** (`services.hyperhive.swarm.domain`),
|
||||
readable only by operators. The per-hive dashboard, on each hive's own
|
||||
domain, covers host-level detail for one hive.
|
||||
|
||||
Distinct from the per-hive dashboard, which lives on the hive domain and
|
||||
answers for one host. This one is the view _across_ hives.
|
||||
## What it shows
|
||||
|
||||
| route | what |
|
||||
| ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `/` | the hive directory, each hive with its last reported status |
|
||||
| `/agents` | every agent: status, config PR, wanted state; create agents, link forge and matrix accounts |
|
||||
| `/agents/<name>/terminal` | one agent's live terminal |
|
||||
| `/jobs` | the controller's job graph — where agent creation and credential mints show progress |
|
||||
| `/issues` | a cross-repo issue report |
|
||||
|
||||
Everything it shows comes from [`swarm-controller`](../../swarm-controller/README.md).
|
||||
An agent created here or with `swarmctl agent create` starts `paused`; set it
|
||||
`up` from its card.
|
||||
|
||||
## Enabling
|
||||
|
||||
|
|
@ -35,28 +48,16 @@ requiring `group:admins`. An account without that group authenticates
|
|||
fine and still gets bounced.
|
||||
|
||||
```sh
|
||||
swarmctl user add <you> --group admins
|
||||
swarmctl user add <you> --email <you>@example.com --group admins
|
||||
swarmctl user update <you> --add-group admins # an account that already exists
|
||||
```
|
||||
|
||||
<!-- vale write-good.Passive = NO -->
|
||||
`--email` isn't needed for the UI, but the forge won't create your account
|
||||
without one → [setup.md § 2](../getting-started/setup.md#2--your-sso-account).
|
||||
|
||||
`admins` deliberately, not a new word: [`../getting-started/setup.md`](../getting-started/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.
|
||||
|
||||
<!-- vale write-good.Passive = YES -->
|
||||
|
||||
An account created without any group needs re-adding with the flag —
|
||||
`swarmctl` reads the existing entry out of `users.yml,` 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
|
||||
include every agent in the hive. The group is the only thing standing
|
||||
between "an operator's page" and "anyone with a session."
|
||||
Why a group and not "any session": agents are authelia subjects too, so
|
||||
_authenticated_ includes every agent in the swarm. The group is the only
|
||||
thing standing between "an operator's page" and "anyone with a session."
|
||||
|
||||
## What it costs to be reachable
|
||||
|
||||
|
|
@ -66,7 +67,22 @@ not a hole: **reachability isn't the access control here.** An agent
|
|||
that resolves the name and connects still has no operator session, and
|
||||
the subrequest denies it.
|
||||
|
||||
## Two wiring sites
|
||||
## Quick links
|
||||
|
||||
The swarm UI's header carries a single 🔗 button, visible on every route,
|
||||
opening a popover of links to other swarm-wide services. Backed by
|
||||
`GET /api/links` (swarm-controller), which serves
|
||||
`services.hyperhive.swarm.controller.links` (a `listOf { label, icon, url }`,
|
||||
same shape as the per-agent `services.hyperhive.agent.dashboardLinks`).
|
||||
|
||||
Each service's own module contributes its entry when it's enabled on the
|
||||
controller's host — `swarm-authelia.nix`, `hive-matrix.nix`,
|
||||
`hive-forge/default.nix`, `swarm-grafana.nix`, `swarm-victorialogs.nix`, and
|
||||
`swarm-ui.nix` for this UI's own API docs. Adding a link for a new service is
|
||||
a nix-only change to that service's module, or an operator adding an entry
|
||||
directly. An empty list hides the button.
|
||||
|
||||
<details><summary>Adding a swarm service name: the two wiring sites</summary>
|
||||
|
||||
Adding a swarm service name means touching two things. Missing the
|
||||
second ships as a different flavour of "works from the host, broken from
|
||||
|
|
@ -99,23 +115,7 @@ and the apex is a **sibling** of `forge.<swarm>` / `chat.<swarm>` /
|
|||
implicitly. Left out, the vhost falls back to the hive leaf and the
|
||||
swarm's front page opens with a name mismatch.
|
||||
|
||||
## Quick links
|
||||
|
||||
The swarm UI's header carries a single 🔗 button, visible on every route,
|
||||
opening a popover of links to other swarm-wide services — authelia,
|
||||
matrix, forge, this UI's own swagger docs. Backed by `GET /api/links`
|
||||
(swarm-controller), which serves `services.hyperhive.swarm.controller.links`
|
||||
(a `listOf { label, icon, url }`, same shape as the per-agent
|
||||
`services.hyperhive.agent.dashboardLinks`).
|
||||
|
||||
Rather than one central hardcoded list, each service's own module
|
||||
contributes its own entry when it's actually enabled on the controller's
|
||||
host — `swarm-authelia.nix`, `hive-matrix.nix` and `hive-forge/default.nix`
|
||||
all do, the same list-merge idiom `gateway.localNames` uses above. Adding a
|
||||
link for a new service is a nix-only change to that service's own module
|
||||
(or an operator adding an entry directly); no swarm-controller or swarm-ui
|
||||
change needed. Empty list hides the button rather than showing an empty
|
||||
popover.
|
||||
</details>
|
||||
|
||||
## Cross-references
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue