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/swarm: state the swarm-services rule once, not per service

Browse source 
mara on the PR: "remove the re stating of the 'follows allSwarmServices'
from the docs everywhere. services md is the central place to explain
what 'all swarm services' means (without listing them)".

Four sections each restated that their service derives from the switch —
authelia, the metrics pair, the log store, the swarm collector. The rule
now lives once at the top of services.md, in the form that carries the
information the four copies did: every optional once-per-swarm service
takes its enable from it.

The intro's enumeration goes with them. Naming the four services in
prose is a hand-maintained list of the same kind, one that a fifth
service does not update.

That also makes an exception legible: swarm-ui's line saying it derives
from the controller rather than from this switch now reads as a real
difference instead of one paragraph disagreeing with four others.
This commit is contained in:
atlas 2026-08-30 19:57:49 +02:00 • committed by mara
commit d7a471043b
1 changed files with 19 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

39
docs/swarm/services.md
View file

@ -1,8 +1,7 @@
# Swarm-wide services
Some things exist once per **swarm**, not once per hive: the forge, the
matrix homeserver, the SSO provider, the CA. Two options say where the
optional ones live, and everything else derives:
Some things exist once per **swarm** rather than once per hive. Two
options say where the optional ones live, and everything else derives:
```nix
services.hyperhive.deploy.singleHostSwarm = true; # everything on this box
@ -10,11 +9,16 @@ services.hyperhive.deploy.singleHostSwarm = true; # everything on this box
services.hyperhive.deploy.allSwarmServices = true;
```
`singleHostSwarm` is the all-on-one-box switch: it defaults both
`deploy.allSwarmServices` (the shared services run here) and
`swarm.ca.autoConfigure` (the swarm CA is generated here). Each derived
toggle can still be set on its own, so "all local except X" needs no
further option.
**`deploy.allSwarmServices` is what "the swarm's shared services run
here" means: every once-per-swarm service that is *optional* takes its
`enable` from it.** That is the whole rule, stated once — the per-service
sections below do not repeat it, so a service that stops deriving is a
visible difference rather than one more paragraph saying the same thing.
`singleHostSwarm` is the all-on-one-box switch above it: it defaults
both `deploy.allSwarmServices` and `swarm.ca.autoConfigure` (the swarm CA
is generated here). Each derived toggle can still be set on its own,
which wins, so "all local except X" needs no further option.
**Both default to off**, and that is deliberate: a host cannot tell
whether it is meant to be the swarm's service host, so this is an
@ -64,8 +68,7 @@ One authelia per swarm, in a `swarm-authelia` container, at
provider, differentiated by roles and claims rather than by mechanism —
there is one IdP and one auth path.
- **`deploy.authelia`** — run the container here. Defaults from
`deploy.allSwarmServices`.
- **`deploy.authelia`** — run the container here.
- **`swarm.authelia.url`** — where clients are sent to authenticate.
Present on **every** hive, defaulting to this host's own instance only
when this module is the thing running it; otherwise `null`, and a hive
@ -98,10 +101,8 @@ one Grafana, in two containers at `metrics.<swarm-domain>` and
`grafana.<swarm-domain>`. Two containers rather than one so Grafana can
be restarted or broken without taking the time-series database with it.
Both follow `deploy.allSwarmServices` like authelia and matrix, so
the swarm's service host gets them with everything else. They derive
together: a store with no UI is unreadable and a UI with no store is
empty. To run one without the other, set it directly:
They derive together: a store with no UI is unreadable and a UI with no
store is empty. To run one without the other, set it directly:
```nix
services.hyperhive.deploy.victoriametrics.enable = true;
@ -132,9 +133,8 @@ the collector is the only intended writer.
### Logs (VictoriaLogs)
The swarm's service containers ship their journals to one VictoriaLogs at
`logs.<swarm-domain>`, behind the same SSO as everything else. It follows
`deploy.allSwarmServices` too, and the collector below is what writes
to it.
`logs.<swarm-domain>`, behind the same SSO as everything else. The
collector below is what writes to it.
**Reading them.** Open Grafana, pick **Explore**, and choose the
`VictoriaLogs` datasource — it is provisioned for you. Grafana's *Logs
@ -160,9 +160,8 @@ and exports to `otel.endpoint`, doing both when both are configured. It
also holds the upstream credential, which is why no hive and no agent
needs one.
It follows `deploy.allSwarmServices` like the services above, in a
`swarm-otel` container. Its `swarm.otel.port` defaults to `4319` rather
than OTLP's usual `4318`, which the hive tier already uses — swarm
It runs in a `swarm-otel` container. Its `swarm.otel.port` defaults to
`4319` rather than OTLP's usual `4318`, which the hive tier uses — swarm
containers share the host's network namespace, so two collectors on one
port is a coin toss at runtime rather than an error at build time.