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: split swarm/deploy options into their own reference pages

Browse source 
services.hyperhive.swarm.* used to carry both swarm-wide facts (name,
domain, hives, ca) and the 'does THIS host run it' toggles for every
swarm service. deploy.nix already split those toggles out into their
own services.hyperhive.deploy.* namespace; this is the docs-side
follow-up now that swarm.* is genuinely swarm-wide-only.

nix/docs/default.nix: host.md drops the swarm/deploy subtrees
(builtins.removeAttrs on the already-picked host tree, not
lib.recursiveUpdate -- that merges rather than deletes, which would
have silently kept them on host.md); swarm.md and deploy.md are new
markdown pages, each its own pickSubtrees root. nix/packages/default.nix
exposes docs-swarm/docs-deploy as flake outputs alongside the existing
docs-host/docs-agent. docs/gotchas.md's Nix options reference section
and docs/swarm/README.md get pointers to the new split.
This commit is contained in:
iris 2026-08-30 04:32:01 +02:00
commit a05d686875
4 changed files with 103 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

19
docs/gotchas.md
View file

@ -452,13 +452,20 @@ hyperhive subsystem `mkForce false` so heavy build inputs stay out of
the eval) and `agentEval` (evaluates `agent.nix` fresh for the
per-agent options tree).
Three output trees consumed by `flake.nix`, all **markdown**:
Five output trees consumed by `flake.nix`, all **markdown**:
- `docs-host` — operator-facing host module options
(`services.hyperhive.*`)
(`services.hyperhive.*` minus the `swarm`/`deploy` subtrees below)
- `docs-swarm` — swarm-wide facts, identical on every host in the swarm
(`services.hyperhive.swarm.*`)
- `docs-deploy` — this host's own deployment decisions, necessarily
different per host (`services.hyperhive.deploy.*` — added by
`nix/host-modules/deploy.nix`, split out of `swarm.*` for exactly this
reason: see that file's own comment)
- `docs-agent` — per-agent harness options (`hyperhive.*`
declared in `nix/agent-modules/`)
- `docs` — bundle of `index.md` + `host.md` + `agent.md`
- `docs` — bundle of `index.md` + `host.md` + `swarm.md` +
`deploy.md` + `agent.md`
Pipeline:
@ -478,7 +485,11 @@ Host options live entirely under `services.hyperhive.*`. The
`pickSubtrees` filter is rooted at `["services" "hyperhive"]` so the
options tree picks up everything under that root — picking against
stray roots produces an empty tree and renders the host page as
template chrome with no `<h2>` headers.
template chrome with no `<h2>` headers. `docs-host` then drops the
`swarm`/`deploy` subtrees from that picked tree (`removeAttrs`, not a
second `pickSubtrees` root — the one exclusion this file needs doesn't
earn a general-purpose helper) since `docs-swarm`/`docs-deploy` each
pick their own root instead.
#### Docs drv stability: `nixSrc`

7
docs/swarm/README.md
View file

@ -5,6 +5,13 @@ coordinate across one or more hives. A single hyperhive instance
running on one host is already a swarm (one hive). This doc covers
the additional config needed when the swarm spans multiple hosts.
For the full option reference rather than prose: `services.hyperhive.swarm.*`
(swarm-wide facts, identical on every host) and `services.hyperhive.deploy.*`
(this host's own deployment decisions — does *this* machine run grafana,
the swarm controller, authelia, …) are separate generated pages, `nix
build .#docs-swarm` / `.#docs-deploy` or the website's `/options/swarm.html`
/ `/options/deploy.html`.
## Terminology
- **hive** — a single hyperhive installation on one host. Has its