diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md index 8bf691ba..6bbd3cf7 100644 --- a/docs/getting-started/setup.md +++ b/docs/getting-started/setup.md @@ -51,11 +51,23 @@ sealed, so the container is up and the port responds while every read times out — the failure looks like a hang, not like a store that was never initialised. Do this before you point anything at it. +Run this **inside the store's container** — `nixos-container root-login +swarm-bao`. The store's TLS certificate is issued for its DNS name and carries +no IP SAN, and that name resolves to the bridge rather than to the container +from in there, so neither `127.0.0.1` nor the name works on its own. Verify the +name while connecting on loopback: + ```bash -# On the host that RUNS the store, once. +export BAO_ADDR=https://127.0.0.1:8200 +export BAO_TLS_SERVER_NAME=bao. # `deploy.bao.domain`, the CN the cert carries + bao operator init # keep the keys it prints and the root token OFF this host ``` +From the **host** instead, `BAO_ADDR=https://bao.:8200` reaches +the same store and needs no SNI override — that's the address every unit in +the tree builds, and what `swarm-controller` connects to. + While you still hold that root token, mint the one credential the swarm needs to grant itself anything. Cert auth answers a _role_, so nothing can authenticate until some role exists — this token is what breaks that cycle,