docs/setup: say WHERE bao operator init runs, and how to reach the store from there

"On the host that RUNS the store" is ambiguous in the deployment we
actually ship: openbao runs inside the `swarm-bao` container, so the
host and the container are different vantages with different working
addresses, and the instruction reads as either.

From inside the container neither obvious address works — the server
certificate is issued for the store's DNS name and carries no IP SAN,
while that name resolves to the bridge rather than to the container. The
fix is an SNI override: verify the name, connect on loopback. The host's
own address is stated beside it so the reader can pick a vantage instead
of discovering the constraint from a TLS error.
This commit is contained in:
atlas 2026-09-10 11:05:35 +02:00
commit d2c501d1b2

View file

@ -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.<swarm domain> # `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.<swarm domain>: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,