docs/gotchas.md: extract nix/{assets,docs,templates/weston-vnc} prose (#718 batch 3)
- assets.nix: cargo-cache-invalidation rationale → "Split asset derivations away from the rust workspace" section. - templates/weston-vnc.nix: port allocation, weston bind-address quirk, PAM service name, Type=simple choice, idle-time=0 → "Weston VNC compositor (per-agent hyperhive.gui.enable)" section. - docs/default.nix: rendering pipeline + subtree-pick + output-tree history → "Nix options reference" section. In-code comments trimmed to short purpose statements + docs pointers. description = '' blocks (operator-facing options docs) preserved per iris #718. `nix flake check` + `nix build .#docs` clean.
This commit is contained in:
atlas
mara
parent
f60a90d752
commit
db2a48cde6
4 changed files with 170 additions and 174 deletions
102
docs/gotchas.md
102
docs/gotchas.md
|
|
@ -238,3 +238,105 @@ and fail outright if the host daemon's
|
|||
`nix/templates/harness-base.nix` does `lib.mkForce true` so builds
|
||||
fall back to unsandboxed local builds rather than failing. Security
|
||||
implications: `docs/security.md`.
|
||||
|
||||
## Split asset derivations away from the rust workspace
|
||||
|
||||
`nix/assets.nix` builds the branding SVG/PNG family + claude
|
||||
system-prompt template + claude-settings JSON as its own derivation,
|
||||
separate from the hive-ag3nt / hive-c0re crates. Reason: when the
|
||||
rust build's `src` was the whole repo tree, any tweak to
|
||||
`branding/agent-configs.svg` or `hive-ag3nt/prompts/system.md`
|
||||
invalidated the cargo cache and forced a full rebuild. crane (and
|
||||
naersk before it) couldn't see "these inputs are unused by rust" on
|
||||
its own — the split breaks the coupling at the derivation boundary.
|
||||
The agent-configs PNG is rendered from the SVG via `rsvg-convert` at
|
||||
build time; librsvg dependency lives here, not in the rust
|
||||
derivation's `nativeBuildInputs`.
|
||||
|
||||
## Weston VNC compositor (per-agent `hyperhive.gui.enable`)
|
||||
|
||||
`nix/templates/weston-vnc.nix` adds an optional Weston Wayland
|
||||
compositor with the VNC backend, surfaced as
|
||||
`hyperhive.gui.enable = true` per-agent. The harness's
|
||||
`/screen/ws` WebSocket relay (`docs/web-ui.md::Per-agent endpoints`)
|
||||
connects to the compositor at `127.0.0.1:<vnc_port>`.
|
||||
|
||||
- **Port allocation**: deterministic FNV-1a of the agent name
|
||||
(read from `/etc/hostname`, leading `h-` stripped) mapped into
|
||||
`[15900, 16799]`. Mirrors the agent web-UI port pattern from
|
||||
`docs/gotchas.md::Web UI ports collide on hash` — same FNV-1a
|
||||
constant, different range. The compositor's startup script writes
|
||||
`/etc/hyperhive/gui.json = {"vnc_port":N,"auth":"none"}` so the
|
||||
harness reads the port at runtime; no nix-side / harness-side hash
|
||||
duplication.
|
||||
- **VNC bind address**: weston's VNC backend has no CLI
|
||||
bind-address flag (unlike the RDP backend's `--address`), so the
|
||||
listener binds `0.0.0.0`. The harness relay only connects via
|
||||
`127.0.0.1`; the host firewall blocks the per-agent VNC port range
|
||||
from external access. A future weston.ini `[vnc] address=` will
|
||||
let us restrict the bind directly once upstream supports it.
|
||||
- **PAM service name**: literal `weston-remote-access` — that's the
|
||||
string libweston passes to `pam_start()` in `libweston/auth.c`.
|
||||
Using `weston` falls back to the system default PAM stack and
|
||||
rejects auth. The service is configured to `pam_permit.so` for
|
||||
all three module types (auth / account / session) so the
|
||||
browser's empty Apple-DH credentials (type 30) always pass —
|
||||
neatvnc ≥ 0.9 calls the PAM auth callback regardless of
|
||||
`weston.ini` `auth-method=none`, so the permit fallback is what
|
||||
actually lets the empty-cred client through.
|
||||
- **`Type = "simple"` (not `notify`)**: `switch-to-configuration`
|
||||
must never block on weston signalling readiness. A misconfigured
|
||||
weston degrades to a `Restart=on-failure` loop visible in
|
||||
`journalctl`, it does not abort the `nixos-container update`.
|
||||
Same reasoning as the `tea-login` unit in `harness-base.nix`.
|
||||
- **`[core] idle-time=0`**: disables weston's 300-second idle
|
||||
timeout. Without it the VNC desktop fades to black and
|
||||
desktop-shell shows its click-to-unlock screen — useless for an
|
||||
agent desktop viewed over `/screen`. `idle-time=0` updates the
|
||||
idle timer with a 0ms delay, which
|
||||
`wl_event_source_timer_update` treats as "disarm", so the
|
||||
compositor never goes idle and never locks.
|
||||
|
||||
## Nix options reference (`nix/docs/default.nix`)
|
||||
|
||||
`pkgs.nixosOptionsDoc` over two evaluated module trees:
|
||||
`hostEval` (a stub NixOS system loading `self.nixosModules.default`
|
||||
with every hyperhive subsystem `mkForce false` so heavy build
|
||||
inputs stay out of the eval) and `agentEval` (reuses the already-evaluated
|
||||
`agent-base` container config so the per-agent options tree is
|
||||
identical to what a real agent container sees).
|
||||
|
||||
Three output trees consumed by `flake.nix`:
|
||||
|
||||
- `docs-host` — operator-facing host module options
|
||||
(`services.hyperhive.*`)
|
||||
- `docs-agent` — per-agent harness options (`hyperhive.*`
|
||||
declared in `nix/templates/harness-base.nix`)
|
||||
- `docs` — bundled static site (`index.html` + `host.html` +
|
||||
`agent.html`, plus `.md` source-of-truth versions of each
|
||||
options page)
|
||||
|
||||
Rendering pipeline:
|
||||
|
||||
- CommonMark from `nixosOptionsDoc.optionsCommonMark` — source of
|
||||
truth, kept as `.md` in the bundle.
|
||||
- HTML via `pkgs.cmark-gfm` over the CommonMark, wrapped in a
|
||||
minimal inline-CSS template. `cmark-gfm` (not plain `cmark`) so
|
||||
any future tables / autolinks Just Work without revisiting.
|
||||
- Inline `<style>` from `nix/docs/style.css` so the bundle is
|
||||
single-file-per-page and nginx's `/options/` mount needs no MIME
|
||||
setup for separate `.css` files and no cache-busting.
|
||||
- Asset paths inside rendered HTML are all relative
|
||||
(`./host.html`, etc.) so the bundle can mount at any URL prefix
|
||||
without rewriting.
|
||||
- `transformOptions` strips the nix-store prefix from option
|
||||
declaration paths and rewrites them as forge URLs, so the
|
||||
rendered docs link back to the source.
|
||||
|
||||
Post-#615 (closes #630) host options live entirely under
|
||||
`services.hyperhive.*`. Pre-#615 had a mix of `hyperhive.*` (forge,
|
||||
matrix, domain) and `services.hive-c0re.*`; picking against the
|
||||
old roots on current main silently produced an empty options tree,
|
||||
so the rendered host page was just template chrome with no `<h2>`
|
||||
headers. The `pickSubtrees` filter is rooted at
|
||||
`["services" "hyperhive"]` for that reason.
|
||||
|
|
|
|||
Loading…
Reference in a new issue