Setup wizard and installation settings

Start the container with a database and two secrets, and finish everything else in the browser. The wizard runs once, on a fresh installation; afterwards the same settings are under Settings → Installation.

What stays in the environment

Only DATABASE_URL, SESSION_SECRET, ENCRYPTION_KEY and PORT must be in the environment (see configuration). Everything else is an installation setting.

Any of them can also be set in the environment under the same name (listed in .env.example). A variable that is set wins and is shown as Set by the environment in the wizard and under Settings → Installation. Every setting, with its default, is in configuration.

First start

With no admin in the database, the desk starts in setup mode:

• Every page leads to /setup, and the API answers 503 setup_required. /healthz reports "setup": true.
• The wizard opens with a setup token, so nobody else can claim a fresh installation.
• Opening the link starts a setup session in that browser and removes the token from the address bar. /setup without it asks for the token, or the whole link, to be pasted in.

Token	How to open the wizard
The one you chose in SETUP_TOKEN (24 characters or more)	Open /setup?token=<SETUP_TOKEN>. It works until the first admin exists. The install guide makes it and prints the link.
Without SETUP_TOKEN	A one-time setup link the desk prints to its log, in a line starting with "No admin yet". The link is the same on every restart until it's used; after that a restart prints a new one.

[!TIP] If the address in the log is wrong (the public address isn't set yet), open /setup?token=… on the address you reach the desk at.

The steps

Each step has a live check. Email, file storage and bot protection can be skipped and finished later.

Name and address → Email → File storage → Bot protection → Licence key → Organization and brand → What it's for → First admin → Two-factor sign-in

1. Name and address: the product name, the public address (checked by the desk calling itself there) and trusted proxies. The step shows the address the desk sees for your request; behind a proxy, add the proxy's address until "your address" is your own.
2. Email: Resend (an API key) or any SMTP server (smtp://user:password@host:587, or smtps:// for port 465), and the default sender. Send test email sends one with the values in the form.
3. File storage: any S3-compatible storage: endpoint, region, bucket (created if missing) and keys. Test upload writes, reads back and deletes a small file.
4. Bot protection: Cloudflare Turnstile site and secret key. The step shows a live widget with the site key; Check the keys sends its token to Cloudflare with the secret key.
5. Licence key: the free key from itsmengine.com, pasted in. The desk checks it offline and shows who it names; the wizard can't finish without one. See the licence key.
6. Organization and brand: the first organization (its name starts as the one on the licence), its case prefix, colours, sender name and address, and a logo. More units and brands come later, under Settings → Organization and Brands.
7. What it's for: what you are setting up (see the choices below).
8. First admin: name, email and password. Creating it finishes setup: the wizard closes for good, and you're signed in.
9. Two-factor sign-in: set up an authenticator app now, or later under Settings → Sign-in and security (admins are asked to before they reach the admin pages).

[!NOTE] Values tried in a check are not saved until you choose Save and continue.

What it's for

Choice	What it turns on
A support desk	The desk on its own: cases from email, forms and portals, with service levels, automations, surveys and reports, and no plugins on.
An IT service desk	Also Service Configuration and Incident Management.
With a software team	Software Development as well.

Admins turn plugins on and off later under Settings → Plugins.

Settings → Installation

The same settings, with the same checks, for admins once the desk runs.

Still to do at the top lists what the installation lacks:

• no public address, or not https
• no email transport
• no file storage (files are then kept in memory and lost on restart)
• no or test Turnstile keys

The same list is in GET /healthz as warnings; the desk stays healthy and starts anyway.

[!IMPORTANT]

Secrets (SMTP address with its password, API keys, the storage secret, the Turnstile secret) are never shown again. Leave the field empty to keep the stored one.

• Every change is in the audit log ("installation.updated", which settings), and changes to the public address and the email transport also record the old and new value.
• With several instances, the others pick up a change within 30 seconds.

Above the settings, Licence: who the licence key names, the plugins and staff users it allows, and Replace key… (see the licence key).

The version and updates have a page of their own, Settings → Updates (see upgrades).