From d2c501d1b2e886d8e4997facef2ecdd1ab838fff Mon Sep 17 00:00:00 2001 From: atlas Date: Thu, 10 Sep 2026 11:05:35 +0200 Subject: [PATCH] docs/setup: say WHERE `bao operator init` runs, and how to reach the store from there MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "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. --- docs/getting-started/setup.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) 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,