Migrations and the onboarding redirect on startup

When MobilityManager starts, it tries to bring the database schema up to date and redirects users to the setup wizard if the system has not been configured yet. Understanding this startup behaviour helps you interpret logs and first-run experiences.

Migrations are applied on startup

On boot, the application runs its database migration routine. It first migrates the system database, then iterates through every active tenant that has a connection-string template and migrates each tenant database in turn.

The process is deliberately fault-tolerant:

• If the database is not reachable or not yet configured, migrations are skipped and a warning is logged — the app still starts so the onboarding wizard can run.
• Non-relational providers (the in-memory fallback used before configuration) are skipped entirely.
• A connectivity check runs before migrating, so an unreachable database logs a clear message rather than crashing startup.

Note: Because migrations run automatically at startup, a rolling deployment applies pending schema changes as the new instance comes up. Plan schema changes to be backward compatible during rollout.

What "configured" means

The application treats itself as configured only when all of the following are true in a reachable, non-in-memory database:

1. At least one user exists.
2. An active license is present.
3. At least one tenant exists.

Until then, the system is considered unconfigured.

The onboarding redirect

An onboarding middleware inspects incoming browser requests. If the system is not configured, it redirects the user to /setup so they can complete the setup wizard. The redirect is skipped for paths that must always work, including:

• API calls under /api/
• The setup and login pages (/setup, /login)
• Health endpoints (/healthz, /livez, /readyz)
• Framework and static asset paths, and any request for a file (paths containing a dot)

Tip: Health probes are exempt from the redirect, so Kubernetes and Compose health checks keep passing even while the system is waiting to be configured.

First-run sequence

1. Start the app with a valid DatabaseProvider and connection strings pointing at empty databases.
2. Startup migrations create the system schema; with no tenants yet, tenant migrations are skipped.
3. A browser request is redirected to /setup.
4. You complete the wizard, which creates the first admin user, activates the license, and provisions the first tenant.
5. Subsequent requests are served normally; the redirect no longer fires.

Related

• Configuring the database connection strings
• Choosing between PostgreSQL and SQL Server
• Understanding the health endpoints
• Troubleshooting a failed startup