First run

A fresh install has no accounts and nothing configured. The first request lands on /setup, and the app serves nothing else until the flow finishes.

The flow

1. Controller or agent. Agents are set up from their own host and paired later; choosing here just says which this is.

2. Create the first administrator, or configure an OAuth provider instead of a local account.

3. Sign in. Deliberately before anything else is entered - a mistyped password or a wrong OAuth client secret is otherwise only discovered after the whole configuration is filled in.

4. Settings. Everything that used to live in .env, pre-filled from whatever the environment already provides, each field showing where its value came from. Save writes them to the database and opens the dashboard.

The stage is derived from what exists rather than tracked as a counter, so a half-finished setup resumes where it left off and the back button cannot desynchronise it. Every screen shows where it sits in the flow, and the stepper reads the same stages the redirects do, so the two cannot disagree.

Setup, simulatedThe real screens against a simulated controller: migrate or start fresh, create an account, sign in, save, restart. Untick the database to drop the migration step.DemoNothing you change here is saved

http://cpm.lan:3000/setup/migrate

A pre-3.0 database is on this host

Start over

1. Migrate
2. 2

   Account
3. 3

   Sign in
4. 4

   Settings

Migrate an existing installation

A database from a previous version is on this host. Migrating copies the parts you choose into PostgreSQL. The original file is not modified.

Databases found

/app/data/caddy-proxy-manager.db

3 users14 proxy hosts6 certificates3.4 MB

Last written 2026-09-21T18:04:12Z

/app/data/caddy-proxy-manager.db.bak

2 users11 proxy hosts5 certificates2.8 MB

Last written 2026-03-02T09:47:55Z

What to migrate

Anything left unticked stays in the old file, which is not modified either way.

Users and their sign-in - 41 rowsAccounts, passwords, API tokens, groups and the per-user access rules on your hosts. Leaving these behind means creating a new administrator on the next screen.

Proxy hosts - 17 rowsYour HTTP and layer-4 hosts, with their mTLS access rules. Certificates and access lists come with them, because a host that lost its access list would be published unprotected.

Certificates - 6 rowsIssued and uploaded certificates, certificate authorities, client certificates and mTLS roles. Required by Proxy hosts.

Access lists - 4 rowsBasic-auth lists and the usernames in them. Required by Proxy hosts.

OAuth providers - 1 rowConfigured identity providers, including their client secrets. Bringing an enabled provider across is a way in on its own, even without the old user accounts.

Agents - 1 rowRemote agents this controller had paired with, and their shared secrets. Required by Proxy hosts.

Settings - 12 rowsThe stored configuration the Settings page writes - primary domain, ACME details, and the rest.

Audit log - 1,873 rowsThe history of who changed what. Usually the largest table, and never load-bearing.

Migrate into an empty database

This copies rows with their original identifiers, so it expects nothing to have been created here yet. Running it against a database that is already in use is not supported.

Migrate this database

Or start fresh

Skip the migration and configure this instance from scratch. The old file is left alone, and this offer will not appear again.

Skip and set up fresh

The administrator password fieldGenerate one and reveal it.DemoNothing you change here is saved

Password ∙ RequiredGenerated passwords are 24 characters from a mixed alphabet.

The sign-in step is the ordinary sign-in screen: the username first, then the password. There is a live one under signing in.

What it decides for you

Setup switches on the dashboard host, so the instance is already reverse-proxying something - itself - before you have created anything. It comes up on HTTP; HTTPS is a check you run once the domain reaches you.

Finishing restarts the application

Saving the last step stores configuration the running process resolved before any of it existed: settings were cached and the enabled identity providers listed at boot, against a database that had neither. So setup restarts the application rather than handing you a process still answering from the empty one, and the screen waits for it to go away and come back. Coming back is also what applies the Caddy configuration, which is how the dashboard host you just created starts answering.

If you gave the dashboard host a domain, that is where you land once it has been confirmed to reach this deployment - otherwise you stay on the address you set up at, which always works. Your session belongs to the address you signed in at, so the new domain asks you to sign in again. A deployment with nothing supervising the container never comes back on its own: the screen says so, and gives you the command to restart it by hand.

Two things skip the flow

• An existing pre-3.0 installation. A SQLite database found on the host is offered for migration before account creation, because you want its accounts rather than a new one alongside them. Secrets are re-encrypted under this deployment’s own key. Starting it asks for confirmation first, restating what will be copied: the rows keep their original identifiers in a database that has to be empty, the application restarts, and leaving the accounts behind means setup goes on to create a first administrator.
• A deployment that predates the flow. If ADMIN_USERNAME/ADMIN_PASSWORD or OAUTH_ENABLED already configure a way in, setup is marked complete at startup and never shown.