Build process

The pnpm workspace links the APIs, UIs and shared libraries. Each component image contains its API and UI and is built with its own Dockerfile-<component> at the repository root. EMBEDDED_FRONTEND enables the bundled UI; the Docker images set it automatically and serve API routes under /api after any public subpath.

From the repository root, use the pinned pnpm version and build the libraries before starting an API:

pnpm install --frozen-lockfile
pnpm build:libs

Run a package script with pnpm --filter @apps/control-plane-api <script>.

Development

Use the managed HTTP sample for the coordinated stack. App-local YAML files are individual service examples; register the exact SSO clients, receiving audiences and provisioning identities before using them. Tenant Management creates or explicitly imports participants.

VS Code settings are included for formatting and debugging. Run the relevant test scripts explicitly when checking a change.

To run the control-plane-ui and control-plane-api in watch mode use the following command:

pnpm dev:control-plane-api

and

pnpm dev:control-plane-ui

For interactions between organizations, use the managed HTTP sample. It provisions Alice and Bob on one Control Plane with separate identities, catalogs and grants. A separate Control Plane process needs its own database, public address, ports and managed service registration; configure those explicitly before starting it.

Docker

Build from the repository root:

docker build -f Dockerfile-control-plane -t control-plane:local .

Run the image with the coordinated service configuration, persistent database and secret references from the managed HTTP sample. Set CONFIG_PATH to the mounted configuration and publish its configured server port. Supply stable SESSION_SECRET and TENANCY_SECRET values and preserve them with the database. The image alone does not provision organizations, browser clients, service grants or the other services in the managed stack.

Database schema migrations

Changes to data access objects (*.dao.ts) can require migrations. Keep separate SQLite (*-sqlite.ts) and PostgreSQL (*-postgres.ts) migrations under src/migrations. Generate them and check for remaining schema changes with:

pnpm --filter @apps/control-plane-api migrations:generate
pnpm --filter @apps/control-plane-api migrations:check

Back up existing databases before applying an upgrade. Schema checks do not establish that an existing participant has been imported into Tenant Management.

Continuous integration

The GitLab pipeline builds components, runs tests and schema checks, scans dependencies and containers, and checks generated configuration and API references. Release publication uses the repository's release jobs. Consult the current pipeline definition for job rules and release parameters.