Deploy production containers

Production deployment is defined by omnia-platform/deploy/compose.prod.yaml, its configuration and Caddy rules. Use this handbook as a reading path and always check the example file from the platform version you deploy.

Prepare the environment

Provide a Docker host and a domain. The reference deployment uses the main domain plus admin., api., desk. and kiosk.. DNS must point to the host. Caddy publishes HTTP/HTTPS and manages certificates.

cp deploy/env.prod.example deploy/.env.prod

Configure database and form secrets, the proxy secret, an appropriate subnet, public domain and SMTP settings. Generate independent random values and keep .env.prod out of Git.

Configure sign-in and access

Configure the OpenID Connect issuer, API audience and scope. Web and admin each need their own client ID and secret. Their callbacks are https://<domain>/auth/callback and https://admin.<domain>/auth/callback.

Set separate random OMNIA_WEB_SESSION_SECRET and OMNIA_ADMIN_SESSION_SECRET values of at least 32 characters each. Only tokens issued to the admin client can confer Owner or Administrator authority; OMNIA_IDENTITY_PRIVILEGED_CLIENTS_CLAIM names the claim that carries the client ID (azp by default, client_id for an RFC 9068 provider). With an issuer configured and no admin client ID, the API refuses to start.

The registration desk signs in as a public client. Set all three of OMNIA_DESK_IDENTITY_AUTHORITY, OMNIA_DESK_IDENTITY_CLIENT_ID and OMNIA_DESK_IDENTITY_API_SCOPE, or none. These values are served to the browser, so never put a secret in them.

Starting Compose is not the same as completing identity setup: verify ownership and access through your provider’s setup procedure.

Start the deployment

From the platform repository:

docker compose -f deploy/compose.prod.yaml \
  --env-file deploy/.env.prod up -d --build --wait

Check the migration run, API readiness, worker and both portals. Test sign-in, an authorised management action and a denied action using a restricted account. Also verify a test message and upload: a reachable homepage does not prove those workflows.

Upgrade from an earlier release

Read deploy/README.md and the upgrade notes in operations before you start the new images. For the reviewed revision:

Replace the single session secret. OMNIA_SESSION_SECRET no longer exists. Generate OMNIA_WEB_SESSION_SECRET and OMNIA_ADMIN_SESSION_SECRET separately. Everyone signs in again afterwards.
Remove the realtime. and displays. hosts. The live-update role and the placeholder room-display app were withdrawn on 9 November 2026. Remove their DNS names and run up --remove-orphans to remove the old containers.
Run the order checks first. The new constraint ck_orders_buyer_shape fails the migration if existing orders break the buyer rules. Run the check query from the operations upgrade notes before upgrading.

Evaluation uses a different profile

deploy/compose.yaml starts the backend evaluation environment. It does not automatically start the full website. The worker also needs the public portal origin for message links. Do not treat production setup as complete before verifying SMTP, identity and storage.

The refresh-coordination reference deployment supports one Docker host. Do not transplant its volumes into an arbitrary multi-host setup. Read operations and recovery before upgrading or restoring backups.