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.
This commit is contained in:
iris
mara
parent
eda7120f08
commit
fbb20a11d2
1 changed files with 80 additions and 20 deletions
|
|
@ -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 <name> --email <address> --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 <name> --email <address> --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.<swarm.domain>` 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://<swarm.domain>/` 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
|
||||
|
|
|
|||
Loading…
Reference in a new issue