First-run setup

A new deployment starts with no people and no administrator. The first administrator is created on the Set up this company page, and the page is protected by a one-time setup token that the application writes to its log.

How first-run setup works#

The first request the application receives on a fresh, empty database creates the company and generates the setup token. The token is written to the application log as an onboarding.bootstrapped event with a setup_token field. Until that first request happens, no token exists.

The setup token does not expire, and it works exactly once. When you use it, the application removes it and closes first-run setup for good.

Find the setup token#

1. Open your deployment's address in a browser once. This first request is what creates the token. You see the Set up this company page.
2. On the host that runs the application, run deploy/find-setup-token.sh. The script reads the app container's log (compose project wi-prod, run with sudo docker compose) and prints the token from the most recent onboarding.bootstrapped line.
3. Copy the printed value.

If the script prints find-setup-token: no 'onboarding.bootstrapped' log line found yet., nobody has visited the deployment's address yet. Visit it once, then run the script again.

You can also read the token straight from the application log: look for the onboarding.bootstrapped line and copy the value of setup_token.

Create the first administrator#

On the Set up this company page ("Paste the setup token for this deployment and create the first admin account."), fill in:

Field	What to enter
Setup token	The token you found above. Surrounding spaces are ignored.
Your name	Your display name.
Your email	The address you will sign in with.
Password	The password for this account.
Confirm password	The same password again.

Select Set up company. The button stays unavailable until every field is filled in.

If the two passwords differ, the page shows "Passwords don't match. Please re-enter them." If the token is wrong or already used, the page shows "Invalid setup link". If the email address already belongs to a person, it shows "A person with email … already exists". For any other failure it shows "Could not set up this company. Check your setup token and try again."

When setup succeeds you are signed in as an administrator with the admin ability and land in the application. From there, invite everyone else from Settings → Administration → Team; see Inviting people.

Things to know#

• The page only appears while no company is set up. Once the first administrator exists, the deployment shows the normal sign-in page instead.
• The token only appears after the first request. If you search the log before anyone has opened the deployment's address, there is nothing to find.
• Keep the token private until you use it. Anyone who holds it can create the first administrator account.
• Email is not required for first-run setup. Configure your company's email settings afterwards if you want invitations delivered by email; otherwise you can share setup links by hand (see Inviting people).