diff --git a/docs/gateway.md b/docs/gateway.md index 1d2c26e9..c0c582ba 100644 --- a/docs/gateway.md +++ b/docs/gateway.md @@ -184,7 +184,7 @@ services.hyperhive.gateway = { nginx inside the gateway container obtains and auto-renews certs via the ACME HTTP-01 challenge on `port` (default 80). The gateway container shares the host network namespace (`privateNetwork = false`) so outbound ACME requests work without any extra routing. Certs are stored inside the container's persistent state dir (`/var/lib/acme/` inside `hive-gateway`; survives restarts because `ephemeral = false`). -**Requirements**: `services.hyperhive.domain` must be publicly DNS-resolvable to this host, and `openFirewall = true` so Let's Encrypt can reach `/.well-known/acme-challenge/`. Each active vhost (main domain, `forge.`, `matrix.`) gets its own cert via separate ACME challenges. +**Requirements**: `services.hyperhive.domain` must be publicly DNS-resolvable to this host, and `openFirewall = true` so Let's Encrypt can reach `/.well-known/acme-challenge/`. Each active vhost (main domain, `forge.`, `chat.`) gets its own cert via separate ACME challenges — the swarm services default to names under `services.hyperhive.swarm.domain`, so **every one of those names must resolve to this host too**, not just the hive's own. Mutual exclusion: `tls.certDir` set together with `tls.acme.enable = true` fails an assertion — pick one external TLS source (or neither, for the self-signed default). @@ -308,8 +308,8 @@ The forge container shares the host network namespace host-side service — nixos-container is here for state + systemd-unit isolation, not network isolation. Note this is the FORGE container; agent containers are network-isolated and reach the forge through the -gateway by `forge.` (see `HIVE_FORGE_URL` above), not via the -host's loopback. +gateway by `forge.` (see `HIVE_FORGE_URL` above), not via +the host's loopback. State lives at `/var/lib/nixos-containers/hive-forge/var/lib/forgejo/` and survives container restart / host reboot. To wipe, destroy the @@ -336,7 +336,7 @@ via `-p 2222`). Port 22 is left alone on the host for openssh. `openFirewall` (default **false**) controls whether `httpPort` and `sshPort` are opened in the host firewall. Off by default (secure by -default): agents reach Forgejo through the gateway (`forge.` on +default): agents reach Forgejo through the gateway (`forge.` on the bridge), not the raw port, so no firewall hole is needed. Flip to `true` when you need: - The operator's browser to reach `http://:/` directly @@ -542,7 +542,7 @@ ordering, preventing the subrequest from looping back through ## Security headers The following headers are emitted at server scope on every gateway -vhost (`_`, `forge.`, `matrix.`): +vhost (`_`, `forge.`, `chat.`): | Header | Value | |--------|-------| diff --git a/docs/matrix.md b/docs/matrix.md index 9e1efcd1..e6c75d90 100644 --- a/docs/matrix.md +++ b/docs/matrix.md @@ -18,7 +18,7 @@ Same shape as [`gateway.md::hive-forge container shape`](gateway.md): separate state dir. - Container shares the host network namespace (`privateNetwork = false`) for state + systemd-unit isolation. Agents - reach the homeserver at `matrix.` via the gateway (agents + reach the homeserver at `chat.` via the gateway (agents run in private netns and can't access host loopback directly). - Persistent state at `/var/lib/nixos-containers/hive-matrix/var/lib/matrix-tuwunel/` @@ -38,9 +38,17 @@ Two distinct hostnames: the hive-gateway serves at that domain. - **`gatewayHost`** — the API listener hostname, where the gateway's matrix vhost proxies `/_matrix/*` to tuwunel. Defaults to - `matrix.` (sub-domain shape). Set to - `null` to skip the gateway vhost (tuwunel stays direct on - `httpPort`). + `chat.` — the **swarm's** domain, + because a swarm runs one homeserver. Set to `null` to skip the + gateway vhost (tuwunel stays direct on `httpPort`). + + ⚠️ Only this one moved. `serverName` still defaults to the bare hive + domain, and the two are independent by design: `gatewayHost` is a + routing detail clients rediscover through `.well-known`, while + `serverName` is baked into every user and room id. A deployment that + wants its old API hostname pins + `gatewayHost = "matrix."` — exactly what the previous + default rendered. **Breaking change**: `serverName` used to default to `matrix.${services.hyperhive.domain}`. Existing homeservers must set @@ -53,7 +61,7 @@ sub-domain from the user-facing identifier. `openFirewall` defaults to `false` (secure-by-default): the host reaches the homeserver on loopback, and agent containers reach it -at `matrix.` via the gateway — so the firewall hole only +at `chat.` via the gateway — so the firewall hole only matters for access from *outside* the host. Flip to `true` when announcing the homeserver to other hives or when an external matrix client needs to reach the client-server API directly. diff --git a/docs/network.md b/docs/network.md index 36aecaf2..54a15428 100644 --- a/docs/network.md +++ b/docs/network.md @@ -46,7 +46,7 @@ untouched by any of it. | container | netns | IPv4 | listens / reached via | | -------------- | ----------------------- | -------------------- | -------------------------------------------------------------------------------------------- | | `hive-gateway` | host (shared) | host addresses | nginx `:80`/`:443` (every vhost); dnsmasq `bridgeIp:53` + DHCP `:67` on the bridge | -| `hive-forge` | host (shared) | host addresses | forgejo `:3000` http, `:2222` git-ssh; fronted by the `forge.` vhost | +| `hive-forge` | host (shared) | host addresses | forgejo `:3000` http, `:2222` git-ssh; fronted by the `forge.` vhost | | `hive-matrix` | host (shared) | host addresses | tuwunel `:8008` (+ optional federation port); fronted by the matrix vhost | | `hive-ci` | private, veth on bridge | DHCP pool | outbound only (runner → forge); no inbound surface | | `h-` | private, veth on bridge | DHCP pool | web UI via UDS `/run/hive-agent/` → nginx sub-path; in-container UI port hashed 8100–8999 | @@ -58,8 +58,9 @@ The flows, end to end: - **DNS** — agents query `bridgeIp:53`; hive zones are answered authoritatively with the bridge IP, everything else forwards to the host's resolvers (see *Resolver behaviour* below). -- **HTTP** — `forge.` / matrix / dashboard names all resolve - to the bridge IP, land on nginx `:80`/`:443`, and proxy to forgejo +- **HTTP** — `forge.` and `chat.` (under `swarm.domain`) plus the hive's + own dashboard name resolve to the bridge IP, land on nginx + `:80`/`:443`, and proxy to forgejo `:3000`, tuwunel `:8008`, hive-c0re `127.0.0.1:7000`, or a per-agent UI unix socket. - **Internet egress** — agent default route points at the bridge IP; diff --git a/docs/turn-loop/config.md b/docs/turn-loop/config.md index 0cfba598..e02c5a45 100644 --- a/docs/turn-loop/config.md +++ b/docs/turn-loop/config.md @@ -157,7 +157,7 @@ evaluated outside a hive. **`hyperhive.matrix.url`** — homeserver URL used by `hive-matrix-daemon` when connecting via the matrix-sdk. hive-c0re writes it into every agent at deploy time as the gateway-routed -`matrix.` URL, so isolated agents can reach the homeserver. +`chat.` URL, so isolated agents can reach the homeserver. Override per-agent when an agent should talk to a different homeserver — for example a remote hive's tuwunel reached over a VPN, or an external Matrix server for a federation-only agent. diff --git a/docs/web-ui/dashboard.md b/docs/web-ui/dashboard.md index bc38230b..3cfc0968 100644 --- a/docs/web-ui/dashboard.md +++ b/docs/web-ui/dashboard.md @@ -692,7 +692,7 @@ in once with the in-host tuwunel homeserver URL (`http://localhost:8008` or whatever the matrix module exposes). The unified nginx-front re-root to -`https://matrix.${hyperhive.domain}` + `.well-known/matrix/client` +`https://chat.${hyperhive.swarm.domain}` + `.well-known/matrix/client` auto-discovery lives in `docs/gateway.md` (atlas's lane). ## FL0W page (`/flow.html`)