Running the platform with Docker Compose for development

The repository includes a Docker Compose stack for local development and testing. It runs a PostgreSQL database and the MobilityManager application (API plus bundled Angular UI) together, with an optional pgAdmin tool. This article walks through using it.

What the stack includes

• postgres — a postgres:16-alpine database, exposed on port 5432, initialised with the system and tenant databases.
• api — the application built from the API service Dockerfile, exposed on port 8080, serving both the API and the UI.
• pgadmin — an optional database UI on port 5050, started only with the tools profile.

The API service runs with ASPNETCORE_ENVIRONMENT=Production and DatabaseProvider=PostgreSQL, with connection strings already pointing at the postgres service.

Provide required settings

The Compose file requires a JWT signing key and accepts a database password. Create a .env file in the repository root:

POSTGRES_PASSWORD=DevPassword123!
JWT_KEY=YourSecretKeyThatMustBeAtLeast32CharactersLong!

Warning: JWT_KEY is mandatory — the stack runs as Production, and there is no committed fallback key, so Compose fails fast if it is missing. Do not reuse the example key from .env.example; it is a known value and is rejected outside Development.

Start the stack

1. Build and start the services:

   docker compose up --build

2. Wait for the database health check to pass; the API waits for a healthy database before starting.
3. Open http://localhost:8080 in your browser. On first run you are redirected to the setup wizard.

Optional database tooling

To start pgAdmin alongside the stack, enable the tools profile:

docker compose --profile tools up -d

pgAdmin is then available on http://localhost:5050 using the credentials from PGADMIN_EMAIL and PGADMIN_PASSWORD.

Check health and stop

The API container has a built-in health check that calls /healthz. You can verify it manually:

curl http://localhost:8080/healthz

Stop and remove the containers when finished:

docker compose down

Note: Database data persists in the postgres_data volume between runs. To start completely fresh, remove volumes with docker compose down -v.

Related

• Running the platform with Docker Compose in production
• Configuring environment variables and the .env file
• Setting the JWT signing key for production
• Understanding the health endpoints