docs: drop statements about absent things, state current behaviour
This commit is contained in:
atlas
parent
4498272276
commit
b83fdc60f3
4 changed files with 22 additions and 30 deletions
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
Every host's nginx: the one front door for whatever this host serves. A swarm service running here (forge, matrix, SSO, the swarm UI, the metrics and log stores) declares its own vhost through the gateway; the gateway itself adds the hive's own surface — dashboard, per-agent UIs, matrix discovery.
|
||||
|
||||
_For the operator configuring `services.hyperhive.gateway.*` on a host._ nginx and the hive resolver (dnsmasq) run on the host next to hive-c0re, not in a container: they bind `:80`/`:443` and the bridge address, so a network namespace of their own would isolate nothing.
|
||||
_For the operator configuring `services.hyperhive.gateway.*` on a host._ nginx and the hive resolver (dnsmasq) run on the host next to hive-c0re, not in a container: they bind `:80`/`:443` and the bridge address.
|
||||
|
||||
You rarely switch it on yourself. `gateway.enable` defaults to off, and every module that serves a vhost or needs hive names to resolve sets `gateway.enable` / `gateway.dns.enable` with `mkDefault true` — the hive controller, each swarm service, CI.
|
||||
|
||||
|
|
@ -41,7 +41,7 @@ Per-agent UIs stay sub-path; forge and matrix get sub-domains → [Sub-domain sh
|
|||
|
||||
## TLS modes
|
||||
|
||||
The gateway always terminates TLS: there is no http-only mode. Which certificate it serves depends on what you configure:
|
||||
The gateway always terminates TLS. Which certificate it serves depends on what you configure:
|
||||
|
||||
| mode | config | cert source | `.well-known` scheme |
|
||||
|---|---|---|---|
|
||||
|
|
@ -77,7 +77,7 @@ The issuer is a **host-held hive CA**, not a bare self-signed leaf. `hive-tls-ca
|
|||
|
||||
⚠️ **Keep the import unit.** It does two jobs nginx needs: it re-modes the key to `0640 root:nginx` (nginx's pre-start `nginx -t` runs as the nginx user and fails on the CA's `0600 root:root` key), and it makes sure **every cert path the config names exists** — when the swarm-services leaf is missing it installs the hive leaf in its place. nginx refuses a config naming a missing cert file, so without that fallback one missing leaf takes down every vhost, not just one.
|
||||
|
||||
**Why a CA, not a bare leaf**: a bare self-signed leaf is its own trust anchor, so every regeneration is a new anchor every consumer must re-trust, and nothing can wire a runtime-generated leaf into an agent's build-time trust store. Agents and federation peers trust the stable CA once; leaf rotation never breaks them.
|
||||
**Why a CA, not a bare leaf**: a bare self-signed leaf is its own trust anchor, so every regeneration is a new anchor every consumer must re-trust, and an agent's build sets its trust store once, before any leaf exists. Agents and federation peers trust the stable CA once; leaf rotation never breaks them.
|
||||
|
||||
**What consumers trust**: `trust-bundle.pem` in the same state dir, not `ca.pem`. The hive CA is an intermediate under the swarm root ([`swarm/ca.md`](../swarm/ca.md) has the hierarchy), and a verifier can't stop at an intermediate — so the bundle carries the hive CA plus its root. nginx serves the leaf with the hive CA appended for the same reason. Agents (via `security.pki.certificateFiles`), the CI and forge containers and federating peers all read the bundle.
|
||||
|
||||
|
|
@ -107,7 +107,7 @@ nginx reads the directory directly. Keep the key readable by nginx:
|
|||
|
||||
### Fronting with an external TLS terminator
|
||||
|
||||
The gateway has no plain-http upstream mode. Either give the gateway the real cert (`tls.certDir` or `tls.acme`) so it serves proper TLS itself, or front it over a unix socket rather than a plain-http TCP port. `.well-known/matrix/*` responses always advertise `https` ([Discovery flow](#discovery-flow-matrix)).
|
||||
Give the gateway the real cert (`tls.certDir` or `tls.acme`) so it serves proper TLS itself, or front it over a unix socket rather than a plain-http TCP port. `.well-known/matrix/*` responses always advertise `https` ([Discovery flow](#discovery-flow-matrix)).
|
||||
|
||||
## HTTP Basic auth
|
||||
|
||||
|
|
@ -234,7 +234,7 @@ matrix-dart-sdk (FluffyChat and others) always fetches the well-known over `http
|
|||
|
||||
Federation peers fetch `.well-known/matrix/server` → `{"m.server":"chat.<swarm>:<httpsPort>"}`. The port is always explicit, even 443: a delegated host without a port means the federation default 8448, not 443. Peers then reach `/_matrix/` on the chat vhost through the gateway, so the gateway must be reachable from them (`gateway.openFirewall`).
|
||||
|
||||
⚠️ The gateway serves both `.well-known` routes on the **hive** vhost. Matrix looks them up at the `serverName`, which defaults to the bare swarm domain, and the swarm UI's apex vhost serves no `.well-known/matrix/*` route.
|
||||
⚠️ The gateway serves both `.well-known` routes on the **hive** vhost only. Matrix looks them up at the `serverName`, which defaults to the bare swarm domain, so a lookup against the swarm domain reaches the swarm UI's apex vhost and finds nothing — pin `serverName` to the hive domain, or serve `.well-known` at the swarm domain yourself.
|
||||
|
||||
## Sub-domain shape (rationale)
|
||||
|
||||
|
|
@ -266,7 +266,7 @@ The `chat.<swarm>` vhost (fluffychat) serves a flutter/SPA bundle via the Accept
|
|||
- hard-refresh on a sub-route must serve `index.html` (SPA's client-side router takes over after JS bootstrap)
|
||||
- a non-navigation request that isn't an on-disk asset must NOT get HTML with the wrong content-type
|
||||
|
||||
Solution: an `nginx http`-context `map $http_accept $matrix_spa_target { ... }` keyed on the request's Accept header. Browser navigations (`Accept: text/html,...`) get `index.html`; everything else (`Accept: image/*`, `*/*`, `application/json`, `text/event-stream`, …) gets a sentinel nonexistent path, so `try_files $uri $uri/ $matrix_spa_target =404` falls through to a plain `404` — a missing asset is just missing. No extension allowlist, no `if` block, no regex heuristics.
|
||||
Solution: an `nginx http`-context `map $http_accept $matrix_spa_target { ... }` keyed on the request's Accept header. Browser navigations (`Accept: text/html,...`) get `index.html`; everything else (`Accept: image/*`, `*/*`, `application/json`, `text/event-stream`, …) gets a sentinel nonexistent path, so `try_files $uri $uri/ $matrix_spa_target =404` falls through to a plain `404` — a missing asset is just missing.
|
||||
|
||||
#### Dashboard: path-based routing (not Accept-header)
|
||||
|
||||
|
|
|
|||
|
|
@ -7,9 +7,7 @@ need the bridge set it with `mkDefault true` — the hive controller, CI,
|
|||
the hive collector, and the gateway's resolver, which every swarm service
|
||||
turns on. Configured via `services.hyperhive.network.*`.
|
||||
|
||||
Isolation is the only mode; agent containers never share the host netns.
|
||||
`services.hyperhive.network.isolateContainers` and
|
||||
`services.hyperhive.network.upstreamDns` don't exist.
|
||||
Agent containers always run in a private netns.
|
||||
|
||||
## Network map
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue