archy/.planning/todos/pending/2026-08-02-onboarding-step-name-your-node.md at feat/podsteadr-app-package

lfg2025/archy

Files

T

archipelagoandClaude Opus 5 6ed876376a docs(todo): onboarding step to name your node (sets the real hostname)

Backend already exists: server.set-name runs hostnamectl set-hostname and
regenerates the TLS cert with a SAN for the new name. This is a UI step.

Records the hazard that decides the design: renaming changes both the mDNS
.local name and the TLS cert, so a rename mid-flow can drop the user's session
in the middle of onboarding — potentially between seed generation and seed
verification. Placement is therefore a design decision, with three options laid
out (last-before-Done, first, or collect-early-apply-late).

Also flags RFC-1123 slugification (users will type "Dorian's Node"), whether
the rename propagates to the Reticulum display name and mesh surfaces, the
reconnection UX, and whether the step is skippable.

Sequenced after the in-flight regenerate_tls_cert atomicity fix, since renaming
is exactly the path that fix protects.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-02 11:39:10 -04:00

4.2 KiB

Raw Permalink Blame History

created, title, area, severity, files

created

title

area

severity

files

2026-08-02T15:30:00.000Z

Add a "name your node" step to onboarding (sets the real hostname)

major

neode-ui/src/views/OnboardingName.vue (to create — match the existing onboarding step design)

neode-ui/src/router/index.ts (:26-76 — the onboarding child routes, in flow order)

neode-ui/src/composables/useOnboarding.ts (step persistence / resume)

neode-ui/src/views/settings/AccountInfoSection.vue (the existing post-onboarding rename UI — reuse its validation)

core/archipelago/src/api/rpc/system/handlers.rs (:462 hostnamectl, :58 + :765 regenerate_tls_cert — backend already exists, no change expected)

Problem

Dorian (2026-08-02): wants a step in the onboarding flow to name your node — in the same design language as the existing steps — which changes the actual hostname.

Today naming only exists after onboarding, in settings/AccountInfoSection.vue. A fresh node keeps its install-time default until the user goes looking for the setting.

What already exists (no backend work expected)

server.set-name (dispatcher.rs:459 → handle_server_set_name) already:

runs sudo hostnamectl set-hostname <name> (system/handlers.rs:462)
regenerates the self-signed TLS cert with a SAN covering <name>, <name>.local, localhost, 127.0.0.1 (:58 → regenerate_tls_cert, :765)
reloads nginx

Current onboarding order (router/index.ts:26-76): Intro → Options → Path → SeedGenerate → SeedVerify / SeedRestore → Did → Identity → Backup → Verify → Done.

The hazard that decides the design

Renaming mid-flow can disconnect the user before their seed is backed up.

The browser is connected to the node over its current hostname and current TLS cert. set-name changes both: the mDNS .local name moves, and the cert is reissued. A user onboarding at https://archipelago.local who renames to mynode can lose the session in the middle of onboarding — potentially between seed generation and seed verification, which is the worst possible moment to drop someone.

That makes step placement a design decision, not an implementation detail. Roughly:

Last, just before Done — everything security-critical (seed shown, verified, backed up) is already complete, so a dropped connection costs nothing but a reload. Safest.
First, before anything else — the rename happens while there is nothing to lose, but the user is asked to name a node before they have any context for what it is, and they may still be mid-redirect when the cert changes.
Defer the apply — collect the name early for good UX, call set-name only at the end. Best of both, at the cost of holding state across steps.

Option 3 or 1 is almost certainly right. This needs deciding explicitly rather than by whichever screen the code lands on.

Also needs deciding / checking

Validation + slugification. Hostnames are RFC-1123: lowercase alphanumerics and hyphens, ≤63 chars, no leading/trailing hyphen. A user will type Dorian's Node. Decide whether to slugify silently, show the slug live ("will be reachable at dorians-node.local"), or reject. Reuse whatever AccountInfoSection.vue already does rather than inventing a second rule.
Does the rename propagate everywhere it should? The Reticulum daemon takes a --display-name, and mesh/FIPS surfaces show node names. Confirm whether set-name updates those or whether the node keeps its old name on the mesh until restart.
Reconnection UX. If the cert/hostname change does drop the session, the step should say so in advance and tell the user where to come back to — not fail silently into a dead tab.
Skippable? A node with no name is fine; forcing a decision at first run is friction. Decide whether the step has a "keep the default" path.

Solution

Own scope — a quick task or a small plan, not a freehand edit, because of the disconnect hazard above. Sequence it after the in-flight regenerate_tls_cert atomicity fix lands (that fix makes the rename path write the key to a staging file and validate before swapping, instead of truncating the live key in place if openssl fails partway — renaming is exactly the path it protects).

4.2 KiB Raw Permalink Blame History