Create the first admin

On a fresh install, the setup wizard creates the first account and makes it the admin. It works once per install: after that, admins are made from the admin area.

Before you start

The Cloud Functions and the Firestore rules are deployed to the project (see Deploy for the first time). The wizard creates the account and the admin role through Cloud Functions, and decides whether setup is needed by reading the database.
The Email/Password sign-in provider is on in Firebase Authentication (see Configure a project).

Run the setup wizard

Open the site, locally at http://localhost:5173 or at its live address. A fresh install sends you to /onboarding, from the home page in npm run dev and from the published one alike.
Create Admin Account: enter your name and your email, twice, then Continue. Use an address you read: it is how you sign in and reset your password.
Set Your Password: at least 8 characters and hard to guess (not 12345678, a common password, or your own name or email), twice, even in an app that chose simple passwords for its members, then Create Admin Account. The wizard creates the account, makes it the admin and waits until your session carries the admin role. This can take a few seconds.
About Your Site: Site Name and Final Site URL, then Continue. This also saves the starting settings: sign-ups open with the user role, uploads converted to WebP, and visitor location lookup on.
Set Up Email: pick a provider (Gmail, SMTP or Resend), fill in its details, click Send a Test Email and give the address to send it to. Continue is enabled once the test passes. Or click Skip for now and set email up later from Settings (see Email engine).
Setup Complete: click Go to Dashboard. The wizard creates an Articles content type, the standard pages (About, Contact, FAQ, Privacy Policy, Terms and Cookie Policy, as drafts in an Info Pages type at /info) and a default signup form (when those features are on), marks setup as finished and opens /admin/dashboard. Going through the wizard again, or pressing Retry, adds nothing that is already there: a content type is only created when no type has its slug.

Run locally, Final Site URL is filled in with http://localhost:5173. Replace it with the site's real address: the sitemap, llms.txt, canonical links and structured data are built from it. You can change it later as Production URL in Settings, About.

How the first account becomes the admin

Nobody can give themselves a role: the security rules never let a person change their own role, and sign-ups create their user record on the server. So the wizard works in two server calls:

The createAccountRecord function creates your record in users with the site's default role, user.
The claimFirstAdmin function makes you the admin. In one transaction it checks that no admin was ever created (no _system/first_admin document and no user with the admin role), then records you in _system/first_admin, sets your role to admin and marks setup as started in Settings/onboarding_status. It then puts arccms_role: admin on your sign-in account as a custom claim, which is what the rules check.

From then on claimFirstAdmin refuses everyone with "This site already has an administrator", so revisiting the wizard cannot take over a finished site. Calling it again as the first admin changes nothing, which lets the wizard retry safely. If your role was taken back before setup finished, reopening the wizard calls it again and it restores your role, but only while setup is unfinished and nobody else is an admin. How roles and claims work in general is on Roles and claims.

Setup counts as finished when Settings/onboarding_status has completed: true. After that, /onboarding sends everyone to the home page.

If you stop halfway

Close the wizard after the account step and the install remembers who started it:

You, signed in: the home page sends you back to the wizard at the site step.
You, signed out: sign in at /signup with the admin account, then open the home page, which sends you back to the wizard. Opening /onboarding while signed out shows Finish setting up, with a link to sign in.
Anyone else: the site as usual. Only the person who started setup can finish it.

After you sign in

An admin lands on /admin/dashboard after signing in (an app can change this in src/custom/home.ts). Good first steps:

Set up email if you skipped it, so sign-up codes and notifications go out.
Fill in the standard pages under Content > Info Pages: replace each [Replace: ...] prompt, then publish (see Standard pages).
Add your content types and templates: Build a website, or Build a custom app.
Give other people admin access from Users (see Users and roles).
Find your way around: Use the admin area.

On an install with adminOnlySignIn on (the default for the backend profile), the wizard closes sign-ups when it finishes, so nobody else can create an account from the sign-in page. See Install profiles.

When it goes wrong

You see	Do this
No wizard on a fresh project	The Firestore rules are not deployed, so the check cannot read the database and assumes setup is done. Deploy them and reload.
"Authentication Disabled"	Turn on the Email/Password provider; the message links to the right console page.
Creating the account fails or never finishes	The Cloud Functions are not deployed to this project. Deploy them, then try again.
"Your administrator permissions have not finished propagating"	Wait a few seconds and try again. If it stays, check that `claimFirstAdmin` is deployed, and look in the function logs for "Refused role" from `onUserRoleChange`: it means the role trigger did not recognize the server's write, so deploy the current functions and reopen the wizard.
"This site already has an administrator" in the browser console	An admin exists. Sign in at `/signup` with that account, or ask that admin for access.
Setup fails on the last step	Click Retry, or Skip & Go to Dashboard, which still tries to create the defaults and finishes setup.