The onboarding wizard: configuring your database

This article covers the first part of the onboarding wizard: opening the setup flow on a brand-new installation and configuring the database. Completing this step prepares the system to store your data.

When the wizard runs

The onboarding wizard runs only while an installation is still unconfigured. When you open a new instance in your browser, you are automatically redirected to the setup route (/setup). The wizard walks through these steps in order:

1. Database configuration
2. Administrator account
3. Licence activation
4. First company/tenant
5. Initial settings
6. Complete

The wizard is intentionally open (no sign-in) because no account exists yet. As soon as setup is finished, these setup screens are permanently sealed off — reopening them returns "The application is already configured. Onboarding is disabled." This is a security measure, so run the wizard only once, during initial setup.

Note: The wizard remembers where you are. If you close the browser midway, reopening the setup route resumes at the step you had reached (for example, the admin-creation step if the database is already configured).

Step 1: Configure the database

This step tells the platform where to store data and creates the system database schema.

Choose the database type

Select one of the two supported engines:

• PostgreSQL — the recommended default, especially on ARM-based servers.
• SQL Server — Microsoft SQL Server, supported for existing environments.

Enter the connection string

Provide the connection string for your database server. The wizard may pre-fill values from the application configuration as a starting point. You only need connectivity to the database server at this stage — the target database itself does not have to exist yet.

Test the connection

1. Select Test connection. The wizard connects to the server (using the server's default administrative database) to confirm it can reach it.
2. If the test succeeds, you see a success confirmation.
3. If it fails, the wizard shows the underlying error message. Check the host, port, credentials, and that the database server is running, then try again.

Configure and create the schema

When you continue, the wizard applies the database schema (migrations) and seeds the permission catalog. If the target database does not exist and automatic creation is enabled, it is created for you. Once this completes, the configured connection is used for the remaining onboarding steps.

Warning: Do not point onboarding at a database that already holds another application's data. The wizard creates and migrates schema on the target server, and re-pointing the connection is exactly the kind of action the platform blocks after setup is complete.

What happens next

After the database is configured successfully, the wizard advances to the administrator account step. The connection details are held for the rest of onboarding and only written permanently to the application settings when you finish the final step.

Related

• The onboarding wizard: admin account, licence, tenant, and settings
• System requirements and supported browsers
• Your first login after setup