Configuration

Application configuration lives in the ignored root .env for local development. The tracked .env.example describes the accepted starting values; pnpm auth:env creates secrets for a fresh installation.

Service addresses

Variable	Purpose
PANEL_ORIGIN	The exact browser-facing panel origin and OIDC redirect origin.
PORT	Local panel port.
API_HOST, API_PORT	API listener interface and port.
API_INTERNAL_URL	API address used by the Next.js server.
OIDC_ISSUER	The configured Keycloak realm issuer; it must match issued tokens.
KEYCLOAK_BACKCHANNEL_URL	API notification address reachable from Keycloak.
POSTGRES_PORT, KEYCLOAK_PORT	Loopback ports published by local Compose.
DOCS_ORIGIN	Documentation origin used by the panel’s Documentation link; local default is port 4321.

Changing origins requires updating the matching client redirects and backchannel configuration. Run the explicit local pnpm auth:configure command after updating identity settings; it is rejected in production.

Secret boundaries

Database credentials, the OIDC client secret, invitation service-account secret and session encryption key are secrets. Keep them out of Git, images, command arguments and browser bundles.

The runtime application database role is separate from the migration owner and the Keycloak database role. It must not own tenant tables or have superuser/BYPASSRLS privileges.

The API session encryption key must remain stable across restarts and instances. Rotating it requires a planned session invalidation and fresh sign-in. Do not regenerate the entire environment to repair a failed login.

Container reachability

Keycloak runs inside Docker while the development API normally runs on the host. The backchannel URL must reach that host process from the container. The local Compose configuration maps host.docker.internal to the host gateway.

On Linux, binding the API exclusively to 127.0.0.1 can prevent container callbacks. In an isolated local development environment, configure an API bind address reachable from Docker and the corresponding backchannel URL. Do not expose development ports on an unprotected public interface.

For optional Mailpit, Keycloak uses the Compose service hostname. The host API may use SMTP_APP_HOST / SMTP_APP_PORT to reach the same mailbox. These overrides are restricted to local plaintext mail and rejected for authenticated TLS SMTP.

Documentation addresses

The static documentation build accepts only these public address inputs:

Variable	Default	Effect
DOCS_SITE_URL	http://127.0.0.1:4321	Canonical site origin and sitemap.
DOCS_PANEL_URL	http://127.0.0.1:3010	Open panel destination.

Pass them as environment variables when building documentation. They are build-time values: rebuild static output when changing them. HTTPS is required for non-loopback origins. Paths, embedded credentials, query strings and fragments are rejected.

The docs build does not load the application’s secret .env. Set the panel’s DOCS_ORIGIN separately when publishing at another origin. Actual production domains and TLS are configured during deployment.

Publishing and independent delivery

RELEASE_DELIVERY_CONFIG points to the worker’s private JSON configuration (signing key path, trusted transport settings and two control addresses). RELEASE_STORAGE_DIR is an absolute permanent private directory, separate from expiring transfer storage. Generate local credentials using pnpm releases:prepare; never put them in a public environment variable or the client bundle. See publishing setup for host/container commands, node settings and the production mTLS boundary.

The worker holds the signing key. Each delivery node receives public verification keys and its own control credential. Existing package reads need none of the management database, API or identity service. The local two-node setup is development infrastructure; production addresses and certificates require separate configuration.

Translation assistance

The optional ASSISTANCE_VAULT_CONFIG_FILE points to a private role-specific JSON file, not a provider key. Use the API encrypt-only identity and a separate assistance-worker decrypt identity. See vault configuration.