First-run setup asks for an organisation and workspace that already exist, and not for the instance URL #2076

Open
opened 2026-11-20 08:59:15 +00:00 by sam · 1 comment
Owner

What happens now

A fresh instance shows a setup screen before anyone can sign in. After commit
904c51024 ("ask for setup one thing at a time") that screen is three steps:

  1. "Set up your organisation" — one field, Name
  2. "Create your first workspace" — one field, Name, prefilled "Default"
  3. "Create your account" — Your name, Email, Password

Submitting posts organisation_name, workspace_name, public_url (currently
window.location.origin) and the account to POST /api/auth/setup.

Before 904c51024 it was two steps and asked for "Organisation name", "First
workspace" and "Instance URL" on the first step.

Why that is wrong

The organisation and the workspace already exist, named, before anyone signs in.
Setup creates neither of them: it renames both. The instance's public URL is the
one value with no source in the tree, and the one value that cannot be corrected
once a passkey exists, so it is the value the first screen is actually about.

Evidence for the two rows already existing:

  • internal/infrastructure/postgres/migrations/0033_org_sys.sql seeds the
    built-in org org-sys with the name "System", and
    internal/domain/storecontract/resource.go defines DefaultOrgID as that id.
  • Every org is created with a workspace named "Default":
    internal/infrastructure/postgres/orgs.go.
  • Setup renames those rows and inserts the public URL: setupAccountOrganisation
    in internal/infrastructure/postgres/accounts.go. The module store does the
    same with an upsert in modules/governance/internal/store/accounts.go, so both
    paths carry the behaviour and both need changing together.
  • Both names are required at bootstrap, which is what forces the questions to
    exist: registrationScope in modules/governance/store_identities.go and
    validateAccountSetup in internal/infrastructure/postgres/accounts.go.

Evidence for the public URL being the constrained value:

  • The update in internal/infrastructure/postgres/authentication.go only
    proceeds while NOT EXISTS (SELECT 1 FROM passkeys), so the stored value is
    frozen at the first enrolled passkey, and a value carried over from the request
    is frozen with it.
  • Passkey relying-party origins are derived from that value
    (modules/governance/store_identities.go), so a wrong origin breaks passkeys
    rather than being cosmetic.
  • Behind a reverse proxy the request's origin is not the instance's public
    address, so the value cannot be derived from the request.

How a comparable product does it

Gitea's installer (in Gitea's own repository) is one page of grouped sections:
database, general settings, optional email, optional administrator account.

  • templates/install.tmpl holds the form. General settings are Site Title, App
    Data Path, Run User, SSH port, HTTP port, Gitea Website URL, and an "allow
    organisations" checkbox that is a registration policy, not an org you create.
  • The public URL is a required field named "Gitea Website URL", helper "Gitea web
    application's public URL for HTTP(S) access, clone URLs and email
    notifications" (options/locale/locale_en-US.json). It is normalised by
    appending a slash and written to [server] ROOT_URL
    (routers/install/install.go).
  • Site Title is the only naming question on the page, helper "You can enter your
    company name here".
  • Nothing creates or names an organisation or a workspace at install. The only
    organisation mention in the installer is that policy checkbox.
  • The administrator account is optional there, described as "Creating an
    administrator account is optional. The first registered user will automatically
    become an administrator". Archie has no self-registration, so its owner account
    has to be asked for.

Wanted

A fresh instance is configured by stating its public URL and creating its first
owner. Organisation and workspace are not questions: the built-in rows keep their
system names.

Open decisions

  • Whether the instance asks for a name of its own (Gitea's Site Title), and if so
    whether that name is the built-in organisation's name.
  • The screen's shape: one page with a section per concern, the Gitea shape, or a
    step per concern.
  • What the built-in organisation shows as its name when the operator has not
    named it, given that it cannot be renamed today (separate issue).
  • Whether a defaulted organisation and workspace name is acceptable at all, or
    whether the built-in rows should be renamed by something else.

Done when

  • POST /api/auth/setup succeeds without an organisation or workspace name and
    leaves the built-in rows unchanged.
  • The first-run screen asks for the instance URL and the owner account only, and
    the URL is stated before any passkey can exist.

Context worth knowing before starting

  • The setup form has no automated coverage: e2e/seed.sh creates the first
    account through the API, and no UI test renders the screen. Anything that
    changes the request shape should say how it was exercised.
  • 904c51024 moved the flow in the opposite direction, splitting the screen into
    three steps and dropping the instance URL field. It should be superseded by the
    work here, not extended.
  • The old archie-ui service and the module store both implement account setup.
    Changing one without the other leaves the two paths disagreeing.
## What happens now A fresh instance shows a setup screen before anyone can sign in. After commit `904c51024` ("ask for setup one thing at a time") that screen is three steps: 1. "Set up your organisation" — one field, Name 2. "Create your first workspace" — one field, Name, prefilled "Default" 3. "Create your account" — Your name, Email, Password Submitting posts `organisation_name`, `workspace_name`, `public_url` (currently `window.location.origin`) and the account to `POST /api/auth/setup`. Before `904c51024` it was two steps and asked for "Organisation name", "First workspace" and "Instance URL" on the first step. ## Why that is wrong The organisation and the workspace already exist, named, before anyone signs in. Setup creates neither of them: it renames both. The instance's public URL is the one value with no source in the tree, and the one value that cannot be corrected once a passkey exists, so it is the value the first screen is actually about. Evidence for the two rows already existing: - `internal/infrastructure/postgres/migrations/0033_org_sys.sql` seeds the built-in org `org-sys` with the name "System", and `internal/domain/storecontract/resource.go` defines `DefaultOrgID` as that id. - Every org is created with a workspace named "Default": `internal/infrastructure/postgres/orgs.go`. - Setup renames those rows and inserts the public URL: `setupAccountOrganisation` in `internal/infrastructure/postgres/accounts.go`. The module store does the same with an upsert in `modules/governance/internal/store/accounts.go`, so both paths carry the behaviour and both need changing together. - Both names are required at bootstrap, which is what forces the questions to exist: `registrationScope` in `modules/governance/store_identities.go` and `validateAccountSetup` in `internal/infrastructure/postgres/accounts.go`. Evidence for the public URL being the constrained value: - The update in `internal/infrastructure/postgres/authentication.go` only proceeds while `NOT EXISTS (SELECT 1 FROM passkeys)`, so the stored value is frozen at the first enrolled passkey, and a value carried over from the request is frozen with it. - Passkey relying-party origins are derived from that value (`modules/governance/store_identities.go`), so a wrong origin breaks passkeys rather than being cosmetic. - Behind a reverse proxy the request's origin is not the instance's public address, so the value cannot be derived from the request. ## How a comparable product does it Gitea's installer (in Gitea's own repository) is one page of grouped sections: database, general settings, optional email, optional administrator account. - `templates/install.tmpl` holds the form. General settings are Site Title, App Data Path, Run User, SSH port, HTTP port, Gitea Website URL, and an "allow organisations" checkbox that is a registration policy, not an org you create. - The public URL is a required field named "Gitea Website URL", helper "Gitea web application's public URL for HTTP(S) access, clone URLs and email notifications" (`options/locale/locale_en-US.json`). It is normalised by appending a slash and written to `[server] ROOT_URL` (`routers/install/install.go`). - Site Title is the only naming question on the page, helper "You can enter your company name here". - Nothing creates or names an organisation or a workspace at install. The only organisation mention in the installer is that policy checkbox. - The administrator account is optional there, described as "Creating an administrator account is optional. The first registered user will automatically become an administrator". Archie has no self-registration, so its owner account has to be asked for. ## Wanted A fresh instance is configured by stating its public URL and creating its first owner. Organisation and workspace are not questions: the built-in rows keep their system names. ## Open decisions - Whether the instance asks for a name of its own (Gitea's Site Title), and if so whether that name is the built-in organisation's name. - The screen's shape: one page with a section per concern, the Gitea shape, or a step per concern. - What the built-in organisation shows as its name when the operator has not named it, given that it cannot be renamed today (separate issue). - Whether a defaulted organisation and workspace name is acceptable at all, or whether the built-in rows should be renamed by something else. ## Done when - `POST /api/auth/setup` succeeds without an organisation or workspace name and leaves the built-in rows unchanged. - The first-run screen asks for the instance URL and the owner account only, and the URL is stated before any passkey can exist. ## Context worth knowing before starting - The setup form has no automated coverage: `e2e/seed.sh` creates the first account through the API, and no UI test renders the screen. Anything that changes the request shape should say how it was exercised. - `904c51024` moved the flow in the opposite direction, splitting the screen into three steps and dropping the instance URL field. It should be superseded by the work here, not extended. - The old `archie-ui` service and the module store both implement account setup. Changing one without the other leaves the two paths disagreeing.
sam added the decisionhigh labels 2026-11-20 08:59:15 +00:00
Author
Owner

Depends on #2077 for anything that relies on the built-in names: dropping the organisation and workspace questions leaves rows whose names cannot be corrected until rename exists.

Depends on #2077 for anything that relies on the built-in names: dropping the organisation and workspace questions leaves rows whose names cannot be corrected until rename exists.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sam/archie#2076