Feature Setup wizard

English · Tiếng Việt · 中文

The first-run setup wizard and the Setup Hub

Since 0.1.3, redesigned in 1.9.0. This page is about the wizard itself — its steps, and the "Setup Hub" screen that replaced a long linear flow. The claim code it starts with is covered in depth on Installation and Security; this page does not repeat that.

What this solves

Getting from "just installed" to "reading mail" needs a handful of decisions made safely (who owns this instance, which database, what the public URL is) without either walking past something irreversible or dropping a brand-new operator straight into a settings screen with a dozen tabs before they have connected a single mailbox.

Where it is

Runs automatically the first time nobody has finished it yet. Reachable again any time afterward from Settings ▸ About ▸ Re-run setup — it is not a one-shot gate, and finishing or skipping it never blocks using the product.

Two halves, split by the login boundary

Before you can sign in (nothing here can sit behind a login, because there is no session yet):

• Claim — proves the person at the keyboard has access to the host, by reading a one-time code from the logs or the CLI. Covered in full on Security.
• Database — shown only when the choice is actually yours to make: it is skipped when DB_DRIVER is locked by the environment, or when a database has already been configured (including returning to this step after restarting onto an external one). See Configuration for the three-plane model behind this.
• Sign-in — creates the actual credential (a passphrase, or the first admin user, depending on AUTH_MODE). The claim code is typed once here and the wizard resends it where needed — earlier versions asked for it twice, once to unlock the database endpoints and once to create the credential, and both of those server-side gates are still independent today; only the UI stopped asking twice.

After you sign in, one required stop and then the hub:

• Identity — the instance's public URL (BASE_URL), asked here because the OAuth redirect URI, the WebSocket origin and the PWA manifest all derive from it.
• The Setup Hub.

The Setup Hub

A grid of status cards, in two framings of the same screen:

• First run shows only three cards — Identity, connecting a Gmail or Outlook account (OAuth), and adding your first mailbox — deliberately kept small. A step earns a place here only if the product does not work without it, is far cheaper to do now than later, or nobody would ever stumble onto it on their own. Everything else is left to be discovered in Settings.
• Settings ▸ About shows the full set — the three above plus sign-in mode, storage, the database, connections, backup, plugins, license and appearance — as a permanent "is this instance actually configured?" checklist. A card that maps to an existing Settings screen (Storage, Connections, Backup, Plugins, License) opens that real screen rather than a second implementation of it.

Each card shows one of five states — done, todo, attention, blocked, or env (the value is locked by an environment variable, shown for information, not action). Attention is amber, deliberately never red: nothing behind it is broken, something is merely still expected of you. The "Add your first account" card is the one exception that stays amber rather than settling into "optional" once you've looked at it, because the product genuinely does nothing useful until a mailbox is connected. The OAuth card is blocked, not merely "todo", until BASE_URL is set — the redirect URI cannot be computed without it.

Finish records completion on the server (owner-only) so the hub stops appearing automatically. Skip deliberately does not record anything, so the hub is offered again the next time — this is a workflow choice, not a bug: dismissing setup once is not the same as declaring it done.

Limits

Available since	0.1.3 (first-run flow); Setup Hub redesign in 1.9.0
Role	pre-login stops need no role at all; Finish is owner-only
Re-run	any time, from Settings ▸ About
First-run cards	3 (Identity, OAuth, first account)
Settings ▸ About cards	the full set — identity, sign-in mode, OAuth, storage, database, connections, backup, plugins, license, appearance, first account

What it does not do

• It does not gate the product. Skipping it, or never finishing it, never prevents SkimMail from being used — it is a checklist, not a lock.
• It does not duplicate other settings screens. A hub card for something that already has a real Settings tab opens that tab; nothing about storage, connections, backup, plugins or licensing is reimplemented here.
• The OAuth card cannot be actioned before BASE_URL is set — this is the one card that is genuinely blocked, not just left undone.

See also

• Installation — the claim code, per install method, and verifying a first start
• Security — the claim code in depth
• Configuration — the three-plane model and the database choice behind the wizard's Database step
• Accounts — the "add your first account" panel is the same Add Account form used everywhere else

---

SkimMail · skimmail@base101.app · 2026-09-15 · commit dffbb18