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:
"Set up your organisation" — one field, Name
"Create your first workspace" — one field, Name, prefilled "Default"
"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
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.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
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:Submitting posts
organisation_name,workspace_name,public_url(currentlywindow.location.origin) and the account toPOST /api/auth/setup.Before
904c51024it was two steps and asked for "Organisation name", "Firstworkspace" 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.sqlseeds thebuilt-in org
org-syswith the name "System", andinternal/domain/storecontract/resource.godefinesDefaultOrgIDas that id.internal/infrastructure/postgres/orgs.go.setupAccountOrganisationin
internal/infrastructure/postgres/accounts.go. The module store does thesame with an upsert in
modules/governance/internal/store/accounts.go, so bothpaths carry the behaviour and both need changing together.
exist:
registrationScopeinmodules/governance/store_identities.goandvalidateAccountSetupininternal/infrastructure/postgres/accounts.go.Evidence for the public URL being the constrained value:
internal/infrastructure/postgres/authentication.goonlyproceeds while
NOT EXISTS (SELECT 1 FROM passkeys), so the stored value isfrozen at the first enrolled passkey, and a value carried over from the request
is frozen with it.
(
modules/governance/store_identities.go), so a wrong origin breaks passkeysrather than being cosmetic.
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.tmplholds the form. General settings are Site Title, AppData 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.
application's public URL for HTTP(S) access, clone URLs and email
notifications" (
options/locale/locale_en-US.json). It is normalised byappending a slash and written to
[server] ROOT_URL(
routers/install/install.go).company name here".
organisation mention in the installer is that policy checkbox.
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 that name is the built-in organisation's name.
step per concern.
named it, given that it cannot be renamed today (separate issue).
whether the built-in rows should be renamed by something else.
Done when
POST /api/auth/setupsucceeds without an organisation or workspace name andleaves the built-in rows unchanged.
the URL is stated before any passkey can exist.
Context worth knowing before starting
e2e/seed.shcreates the firstaccount through the API, and no UI test renders the screen. Anything that
changes the request shape should say how it was exercised.
904c51024moved the flow in the opposite direction, splitting the screen intothree steps and dropping the instance URL field. It should be superseded by the
work here, not extended.
archie-uiservice and the module store both implement account setup.Changing one without the other leaves the two paths disagreeing.
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.