Control-plane environment variables
Server identity, database pools, workers, HA, licensing, and deployment bundle inputs.
Control-plane environment variables configure service identity, listening endpoints, database access, execution workers, and installation licensing.
Read environment loading before setting
values. Edit deployment values in the release bundle's infra.env or the corresponding
Kubernetes ConfigMap and Secret, then restart the affected service.
Server identity and listeners
INFRA_PUBLIC_URL
Type: HTTPS origin. Default: required.
External console and API origin with no path, query, or trailing slash. Startup rejects an invalid origin. SSO and WebAuthn use this identity; changing it requires the origin migration.
INFRA_SERVICE_ROLE
Type: enum. Default: all.
Accepts all, api, worker, or scheduler. Split roles use the same installation database and compatible release. This selects process responsibilities, not user permissions.
INFRA_INSTANCE_ID
Type: string. Default: generated per process.
Distinguishes a control-plane process in logs and worker coordination. An explicit value must be unique among active replicas; it is not the persistent installation ID.
INFRA_LISTEN_ADDRESS
Type: IP literal. Default: 0.0.0.0.
Application listener inside the container. Invalid IP literals reject startup. Public exposure is controlled separately by the published port or ingress.
INFRA_HTTP_PORT
Type: integer port. Default: 8080.
Inclusive range 1–65535. Used by the application listener; it does not change INFRA_PUBLIC_URL or a reverse proxy's external port.
INFRA_TLS_MODE
Type: enum. Default: proxy.
Accepts proxy or direct. Proxy mode expects TLS at a trusted edge. Direct mode requires INFRA_TLS_CERT_FILE and INFRA_TLS_KEY_FILE.
INFRA_TLS_CERT_FILE
Type: absolute input path. Default: unset.
Required in direct TLS mode. Must contain a readable PEM certificate chain matching the public origin. Invalid or expired material fails readiness.
INFRA_TLS_KEY_FILE
Type: absolute secret path. Default: unset.
Required in direct TLS mode. Must be a readable PEM private key matching the certificate; it is never emitted in diagnostics.
INFRA_TLS_CLIENT_CA_FILE
Type: absolute input path. Default: unset.
Optional CA bundle for configured management-client TLS verification. An invalid bundle rejects startup. It does not turn a public API token into a node identity.
INFRA_STATE_DIR
Type: absolute directory. Default: /var/lib/infra.
Persistent installation state. Must be writable by the service account. Derived local data paths use this directory unless explicitly overridden.
INFRA_ENCRYPTION_KEY_FILE
Type: absolute secret path. Default: /run/secrets/infra-encryption-key.
Required persistent root encryption material. The file contains a base64-encoded 32-byte key. Missing, unreadable, or invalid material blocks protected-state initialization. Preserve it with control-plane recovery.
INFRA_SETUP_ENABLED
Type: boolean. Default: true.
Permits setup only while the installation is uninitialized. Setting true cannot reopen a completed setup or replace its recovery owner.
INFRA_SETUP_TOKEN_FILE
Type: absolute output path. Default: /var/lib/infra/setup-token.
Location for the one-time token during initialization. Its parent must be writable. This is an output file, not a supplied API credential; the file is removed after setup.
INFRA_SHUTDOWN_TIMEOUT_SECONDS
Type: integer seconds. Default: 120.
Inclusive range 10–3600. Bounds graceful process shutdown. Expiry does not prove a remote operation stopped; unfinished steps reconcile after restart.
Database and connection pool
INFRA_DATABASE_URL
Type: PostgreSQL URL. Default: unset; the bundle configures it.
Required through this value or INFRA_DATABASE_URL_FILE. Selects the authoritative control-plane database. An unreachable database fails readiness rather than creating a replacement database.
INFRA_DATABASE_URL_FILE
Type: absolute secret path. Default: unset.
Alternative source for the full PostgreSQL URL. Mutually exclusive with INFRA_DATABASE_URL. The service reads it at startup and rejects an empty value.
INFRA_DATABASE_SSL_MODE
Type: enum. Default: verify-full.
Accepts disable, require, verify-ca, or verify-full. The bundled private database configuration explicitly selects its intended mode. External production endpoints should retain hostname and issuer verification.
INFRA_DATABASE_CA_FILE
Type: absolute input path. Default: system trust.
Optional database CA bundle. Verification modes reject an untrusted issuer or mismatched hostname rather than silently falling back to encryption without verification.
INFRA_DATABASE_POOL_MIN
Type: non-negative integer. Default: 2.
Minimum idle connections per process. Inclusive range 0–100; must not exceed the maximum.
INFRA_DATABASE_POOL_MAX
Type: positive integer. Default: 20.
Maximum connections per process, inclusive range 1–1000. Size the database limit for the sum across API, worker, and scheduler replicas.
INFRA_DATABASE_CONNECT_TIMEOUT_SECONDS
Type: integer seconds. Default: 10.
Inclusive range 1–120. Limits connection establishment; it does not bound the lifetime of accepted infrastructure operations.
INFRA_DATABASE_STATEMENT_TIMEOUT_MS
Type: integer milliseconds. Default: 30000.
Inclusive range 1000–600000. Default query timeout for normal application statements. Coordinated migration jobs use their release-specific timeout.
INFRA_DATABASE_MIGRATIONS
Type: enum. Default: auto.
Accepts auto, manual, or disabled. Auto is for the coordinated single-host bundle. HA deployments use a single manual migration job before compatible services become ready.
Workers and high availability
INFRA_HA_ENABLED
Type: boolean. Default: false.
Enables the multi-replica deployment checks. Requires a supported shared persistence topology and one authoritative database writer. It does not create additional replicas.
INFRA_WORKER_CONCURRENCY
Type: positive integer. Default: 16.
Maximum active execution steps per worker process, inclusive range 1–256. Feature and regional concurrency limits can be lower.
INFRA_SCHEDULER_INTERVAL_MS
Type: integer milliseconds. Default: 1000.
Inclusive range 100–60000. Interval for checking newly eligible scheduled work; it is not an execution-start guarantee.
INFRA_RECONCILE_INTERVAL_SECONDS
Type: integer seconds. Default: 15.
Inclusive range 1–300. Determines when unresolved component state is revisited. Repeated checks do not bypass unavailable authoritative state.
INFRA_OPERATION_LEASE_SECONDS
Type: integer seconds. Default: 60.
Inclusive range 15–600. Coordination lease for a worker claim. Losing a claim triggers reconciliation and does not establish guest or storage fencing.
INFRA_OPERATION_HEARTBEAT_SECONDS
Type: integer seconds. Default: 10.
Inclusive range 1–120; must be less than one third of the operation lease. Cross-field violations reject startup.
INFRA_WORKER_RETRY_LIMIT
Type: non-negative integer. Default: 5.
Inclusive range 0–20 for eligible execution-step retries. Zero disables automatic retries, not reconciliation. Validation and ownership errors remain non-retryable.
INFRA_API_BODY_LIMIT_BYTES
Type: positive integer bytes. Default: 1048576.
Inclusive range 65536–16777216. Larger ordinary JSON bodies receive 413. Dedicated artifact upload and signed-object paths have separate limits.
INFRA_RATE_LIMIT_REQUESTS_PER_MINUTE
Type: positive integer. Default: 600.
Default ordinary API credential bucket, inclusive range 60–60000. Specific resource and organization policies can be stricter; clients read response headers.
Licensing and deployment bundle
INFRA_LICENSE_KEY_FILE
Type: absolute secret path. Default: required.
Signed installation entitlement. Offline installations stage it with their approved release artifacts. Missing or invalid entitlement prevents new licensed administration; it does not issue guest shutdowns.
INFRA_LICENSE_SERVER_URL
Type: HTTPS URL. Default: unset.
Optional approved entitlement-refresh endpoint. Offline installations leave it unset and use a valid staged entitlement.
INFRA_LICENSE_REFRESH_SECONDS
Type: integer seconds. Default: 86400.
Inclusive range 3600–604800. Refresh schedule when a server is configured; a refresh attempt does not change the entitlement's signed validity period.
INFRA_RELEASE
Type: string. Default: required in the Compose bundle.
Pinned release tag or digest used by the deployment bundle. It is consumed by Compose, not as a substitute for the running service's observed version.
INFRA_COMPOSE_PROJECT
Type: string. Default: infra.
Bundle namespace for containers and persistent volumes. Changing it can select different volumes; preserve the intended data mapping during upgrades.
INFRA_HTTP_PUBLISHED_ADDRESS
Type: IP literal. Default: 127.0.0.1.
Host-side bind address for the Compose application port. An ingress or reverse proxy normally provides external HTTPS. This does not change the container listener.
INFRA_HTTP_PUBLISHED_PORT
Type: integer port. Default: 8080.
Host-side port, inclusive range 1–65535. It must agree with reverse-proxy routing; it does not rewrite the public origin.