From fbb20a11d27832bea0a52800b2561f0272412986 Mon Sep 17 00:00:00 2001 From: iris Date: Mon, 9 Nov 2026 21:12:27 +0100 Subject: [PATCH] docs: the setup page leads with swarmctl setup, with sample output The first-run page opened with ten hand-run steps and a pointer to the interactive tool. It now opens with swarmctl setup, a sample session and a sample of setup status, and the by-hand steps follow as a reference. --- docs/1-getting-started/setup.md | 100 +++++++++++++++++++++++++------- 1 file changed, 80 insertions(+), 20 deletions(-) diff --git a/docs/1-getting-started/setup.md b/docs/1-getting-started/setup.md index e44b70a9c..1f1ecba52 100644 --- a/docs/1-getting-started/setup.md +++ b/docs/1-getting-started/setup.md @@ -1,31 +1,91 @@ # First-run setup -What's left to do by hand after the first `nixos-rebuild switch` of the +What's left after the first `nixos-rebuild switch` of the [README's all-local quick start](../../README.md#quick-start-an-all-local-swarm) -— from a freshly built host to your first agent. Do the steps in order; -each one assumes the ones before it. Step 0, the NixOS flake, module and -required options, is [`nixos.md`](nixos.md). +— from a freshly built host to your first agent. Step 0, the NixOS flake, +module and required options, is [`nixos.md`](nixos.md). Everything after that is +one command, run as **root on the host**: -Every command runs as **root on the host**. +```bash +swarmctl setup +``` -**Or just run `swarmctl setup`.** It walks the steps below interactively as root: it checks -where you stand first, so a rerun continues where it stopped; shows `Step n of N`; prompts for -what each step needs; shows a running action as one live line; and prints the secrets you must -record, such as the store's keys and root token, under a ⚠️ warning until you confirm you stored -them. A step this host can't do, because it doesn't run that service, names the deploy option -it needs and the host to run `swarmctl setup` on. Steps with no verb yet print their command and -wait for you. The sections below are the same steps by hand. +It walks the ten steps interactively, in order. It checks where you stand +first, so a rerun continues where it stopped. It shows `Step n of N`, prompts +for what each step needs, shows a running action as one live line, and prints +the secrets you must record under a ⚠️ warning until you type `yes` to say you +stored them. A step this host can't do, because it doesn't run that service, +names the deploy option it needs and the host to run `swarmctl setup` on. -Run `swarmctl setup status` at any point to see how far you have got. It lists -the hand steps below, numbered 1 to 10 in the order the sections run them, marks -each done, not done or unknown, shows a progress bar, and names the next one. It changes nothing. +A session that starts at the SSO account, with the store already set up, +looks like this: + +```console +# swarmctl setup +swarmctl setup: 10 steps, 5 left to do + ✔ 1 secret store initialised + ✔ 2 secret store unsealed + ✔ 3 granter bootstrapped + ✔ 4 granting units active + ✔ 5 store unsealed after the granting units + ○ 6 SSO account in the admins group + ○ 7 first swarm UI and forge login + ○ 8 forge site admin + ○ 9 ruth created and up + ○ 10 another agent (optional) + +Step 6 of 10: SSO account in the admins group (5 left, this one included) +no enabled user in the "admins" group; the placeholder is disabled +Your SSO account is made in the `admins` group, which the swarm UI gates on. +Username: mara +Display name [mara]: Mara +Email address (the forge needs one): mara@example.com +✔ added mara +⚠️ Its generated password follows. It is shown once and stored nowhere. + +password: … + +Type `yes` once you have stored the password: yes +``` + +Steps the tool can't do for you print their command and wait: the unseal under +the `shamir` seal, the restart after the granter, and the browser login. + +Run `swarmctl setup status` at any point to see how far you have got. It +changes nothing, and it works from a script: it exits 0 when every step it can +see has finished. + +```console +# swarmctl setup status +🏗️ setup: 6/8 steps done ███████░░░ ❓ 2 unknown + +✅ 1 secret store initialised +✅ 2 secret store unsealed +✅ 3 granter bootstrapped the granting units log in through it +✅ 4 granting units active 2 units +✅ 5 store unsealed after the granting units +👉 6 SSO account in the admins group no enabled user in the "admins" group; the placeholder is disabled + ↳ setup.md § 2: `swarmctl user add --email
--group admins` +❓ 7 first swarm UI and forge login unknown (not observable: a browser login leaves nothing to read) +❓ 8 forge site admin unknown (not observable: the controller has no read route for it; `forge make-admin` is safe to re-run) +⬜ 9 ruth created and up ruth is declared paused +✅ 10 another agent [optional] 1 besides ruth + +next: step 6, setup.md § 2: `swarmctl user add --email
--group admins` +``` > **Not all-local?** Each step says which host it runs on. A split swarm > also has credentials you can't generate where they're read — each > host's mTLS identity at the secret store. Read [`2-handbook/swarm/credentials.md`](../2-handbook/swarm/credentials.md) first; it > says which files you place, and where. -## 1 · Secret store +## The steps by hand + +The sections below are the same steps, one command each. Use them to know what +a step does, to script one, or to redo one. Do them in order; each one assumes +the ones before it. + +### 1 · Secret store _On the host running `swarm-bao`._ Everything else fetches its credentials from the store, so it comes first. @@ -80,7 +140,7 @@ With the default `pkcs11` seal the store unseals itself from here on. With What the granter is, why it's root-equivalent, and the store's TLS: [`4-implementation/swarm/bao.md`](../4-implementation/swarm/bao.md). -## 2 · Your SSO account +### 2 · Your SSO account _On the host running authelia._ Until this runs, `auth.` serves a login page that refuses everyone: its only subject is a placeholder marked `disabled`. @@ -98,7 +158,7 @@ It prints a generated password once — record it. Keep both flags: Fix either afterwards with `swarmctl user update mara --add-group admins --email …`. Details: [`2-handbook/swarm/sso.md`](../2-handbook/swarm/sso.md). -## 3 · Swarm UI login +### 3 · Swarm UI login Open `https:///` and sign in with the account from step 2. The name resolves on the box itself through `/etc/hosts`; from anywhere else it @@ -117,7 +177,7 @@ SSO login asks for its forge password once, to link the two. Agents learn your pronouns from the **Pronouns** field of your forge profile settings. Leave it empty and agents refer to you by name only. -## 4 · Clippy, then ruth +### 4 · Clippy, then ruth hive-c0re creates no agent at startup. On the swarm UI's start page, the paperclip (clippy, the setup assistant) offers to set up ruth, the manager @@ -134,7 +194,7 @@ On a hive that already has a ruth container from an earlier release, create her once the same way, so that her config repo and store identity exist. The container keeps starting with the hive meanwhile. -## 5 · Ask ruth for further help +### 5 · Ask ruth for further help From here on, ask ruth. Open her card on `/agents` in the swarm UI and use the message box under her terminal. She is the manager agent: her MCP surface is the