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:
parent
eda7120f08
commit
fbb20a11d2
1 changed files with 80 additions and 20 deletions
|
|
@ -1,31 +1,91 @@
|
||||||
# First-run setup
|
# 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)
|
[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;
|
— from a freshly built host to your first agent. Step 0, the NixOS flake,
|
||||||
each one assumes the ones before it. Step 0, the NixOS flake, module and
|
module and required options, is [`nixos.md`](nixos.md). Everything after that is
|
||||||
required options, is [`nixos.md`](nixos.md).
|
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
|
It walks the ten steps interactively, in order. It checks where you stand
|
||||||
where you stand first, so a rerun continues where it stopped; shows `Step n of N`; prompts for
|
first, so a rerun continues where it stopped. It shows `Step n of N`, prompts
|
||||||
what each step needs; shows a running action as one live line; and prints the secrets you must
|
for what each step needs, shows a running action as one live line, and prints
|
||||||
record, such as the store's keys and root token, under a ⚠️ warning until you confirm you stored
|
the secrets you must record under a ⚠️ warning until you type `yes` to say you
|
||||||
them. A step this host can't do, because it doesn't run that service, names the deploy option
|
stored them. A step this host can't do, because it doesn't run that service,
|
||||||
it needs and the host to run `swarmctl setup` on. Steps with no verb yet print their command and
|
names the deploy option it needs and the host to run `swarmctl setup` on.
|
||||||
wait for you. The sections below are the same steps by hand.
|
|
||||||
|
|
||||||
Run `swarmctl setup status` at any point to see how far you have got. It lists
|
A session that starts at the SSO account, with the store already set up,
|
||||||
the hand steps below, numbered 1 to 10 in the order the sections run them, marks
|
looks like this:
|
||||||
each done, not done or unknown, shows a progress bar, and names the next one. It changes nothing.
|
|
||||||
|
```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
|
> **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
|
> 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
|
> 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.
|
> 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
|
_On the host running `swarm-bao`._ Everything else fetches its credentials
|
||||||
from the store, so it comes first.
|
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:
|
What the granter is, why it's root-equivalent, and the store's TLS:
|
||||||
[`4-implementation/swarm/bao.md`](../4-implementation/swarm/bao.md).
|
[`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
|
_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`.
|
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
|
Fix either afterwards with `swarmctl user update mara --add-group admins
|
||||||
--email …`. Details: [`2-handbook/swarm/sso.md`](../2-handbook/swarm/sso.md).
|
--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
|
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
|
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
|
Agents learn your pronouns from the **Pronouns** field of your forge profile
|
||||||
settings. Leave it empty and agents refer to you by name only.
|
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
|
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
|
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
|
her once the same way, so that her config repo and store identity exist. The
|
||||||
container keeps starting with the hive meanwhile.
|
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
|
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
|
message box under her terminal. She is the manager agent: her MCP surface is the
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue