From 8d21a47f4212faa8c08e7c16d2fef981adbe83f8 Mon Sep 17 00:00:00 2001 From: atlas Date: Wed, 5 Aug 2026 18:00:14 +0200 Subject: [PATCH] docs(swarm): the shared-services switch and the SSO provider Names the one toggle and what derives from it, and the authelia shape: container where the swarm's services live, client pointer everywhere, users database written by swarm-controller rather than by hand. --- docs/swarm.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/docs/swarm.md b/docs/swarm.md index 747fe480..f6cd4bb4 100644 --- a/docs/swarm.md +++ b/docs/swarm.md @@ -113,6 +113,60 @@ the CA is re-issued under the root and the leaf re-signed. Until then the hive serves TLS exactly as before and is simply not part of the swarm's trust hierarchy. +## Running the swarm's shared 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 they +live, and everything else derives: + +```nix +services.hyperhive.enableAllLocalDefaults = true; # everything on this box +# or, for a dedicated services host with hives elsewhere: +services.hyperhive.swarm.enableRequiredServices = true; +``` + +`enableAllLocalDefaults` is the all-on-one-box switch: it defaults both +`swarm.enableRequiredServices` (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. + +**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 +operator saying so rather than something inferred. With them off, a hive +is a *client* of those services — it configures how to reach them and +runs none of them. + +### SSO (authelia) + +One authelia per swarm, in a `swarm-authelia` container, at +`auth.`. Operator and agents are both subjects of the same +provider, differentiated by roles and claims rather than by mechanism — +there is one IdP and one auth path. + +- **`swarm.authelia.enable`** — run the container here. Defaults from + `swarm.enableRequiredServices`. +- **`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 + joining someone else's swarm sets it explicitly. Null means "no SSO + configured", and consumers say so rather than guessing an address. + +The users database is written by swarm-controller, not by hand: agents +are created and destroyed continuously, so the subject set is dynamic. +This module only guarantees the file exists and parses, so authelia +starts with nobody in it rather than failing to start — a provider with +no subjects yet is the correct state before anything has provisioned +them. Session and storage keys are generated in the container on first +boot and never rotated automatically; replacing one invalidates data +already written (sessions, the encrypted store), so that is an operator +action. + +Storage is local sqlite and the notifier writes to a file. Both are +small-deployment choices, and the scope is the justification: redis +buys shared session state across replicas and there is one instance; +SMTP exists to mail humans, and provisioning here is programmatic. + ## Declaring peer hives ```nix