From d6ca52535f9303e199f9bde42834785c137533c3 Mon Sep 17 00:00:00 2001 From: atlas Date: Sun, 30 Aug 2026 14:46:57 +0200 Subject: [PATCH] docs: give the deployment shapes one home and link to it The three supported shapes were described in pieces across the swarm docs, so a reader assembling them got a different answer depending on which page they landed on. They live in services.md now, and the other pages point at it. Split out of #3719 at mara's request: that PR also rewrites the snapshot-store doc, which is a separate argument. --- CLAUDE.md | 3 +++ docs/swarm/secrets.md | 8 ++++++-- docs/swarm/services.md | 30 ++++++++++++++++++++++++++++++ 3 files changed, 39 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 66f1b934..09126243 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -238,6 +238,9 @@ read them à la carte. - **"How do I connect two hives into a swarm? How do I declare peer hives and configure TLS trust?"** → [`docs/swarm/`](docs/swarm/README.md). +- **"Which deployment shapes are supported — all-local, services on the + controller host, fully spread out?"** → + [`docs/swarm/services.md`](docs/swarm/services.md#deployment-shapes). - **"Where do agent snapshots go? How does the swarm's `btrfs receive` endpoint authenticate a pushing hive, and what does a snapshot actually contain?"** → diff --git a/docs/swarm/secrets.md b/docs/swarm/secrets.md index cd5b2e23..a44b52ac 100644 --- a/docs/swarm/secrets.md +++ b/docs/swarm/secrets.md @@ -25,9 +25,13 @@ missing, and a secret minted on another container's first boot does not exist yet. Binding it would make one container wait on a file that waits on a container that starts after it. -## The three topologies +## Topologies, by who places secrets -Every row below is read against one of these. +Every row below is read against one of these. This is a different cut +from the [deployment shapes](services.md#deployment-shapes) --- those +say *where services run*, these say *who is responsible for a secret +file being there* --- so the two lists do not line up one-to-one, and +neither is a renaming of the other. | topology | what it means | who places secrets | |---|---|---| diff --git a/docs/swarm/services.md b/docs/swarm/services.md index c3de4e08..de95ad87 100644 --- a/docs/swarm/services.md +++ b/docs/swarm/services.md @@ -27,6 +27,36 @@ swarm-wide but **not optional**, being the canonical store for the meta flake and every agent's config repo, so it deploys with hyperhive itself and has no `enable` to derive from anything. +## Deployment shapes + +Those two options are what makes the difference between deployments, so +the shapes worth naming are the ones they produce: + +- **All-local.** Everything on one machine: + `enableAllLocalDefaults = true`. Setup is automatic apart from + choosing a domain and creating the first user. +- **Services on the swarm controller host.** + `swarm.enableRequiredServices = true` there; the required services + deploy together on that host, with hives elsewhere. +- **Fully spread out.** One container / VM / machine per service, + somewhere. + +**These are a set, not a ladder with a correct top, and in-between +shapes are supported.** Each derived toggle can be set on its own (see +above), which is what makes "all local except X" a configuration rather +than an unsupported edge case. Nothing in hyperhive prescribes a +deployment model, so a doc that treats one shape as the real one and +the others as compromises is wrong about the system rather than +opinionated. + +The practical consequence is that **co-location is normal**: in the +first two shapes services share a host by design. Where a specific +service has something to say about sharing a host --- extra +requirements, or a cost worth weighing --- that belongs in the doc for +that service, not here. + +## Services + ### SSO (authelia) One authelia per swarm, in a `swarm-authelia` container, at