Message Ops does not use a single customer YAML configuration file. Infrastructure supplies process environment variables and secret references; the application stores environments, broker credentials, users, roles, sign-in policy, SSO providers, telemetry settings and retention settings in PostgreSQL through the UI/API.
Set NODE_ENV=production explicitly. Only development and test relax runtime hardening; an unset value defaults to development. Startup settings require a restart/redeployment. Saved application settings apply according to their reload or session rules. Configuration Examples shows the production origin and secret mapping.
Required production secrets
| Variable | Consumers | Requirement |
|---|---|---|
DATABASE_URL | API, Worker | Nonempty PostgreSQL URL using the restricted runtime login and certificate-verified TLS. |
DATABASE_URL | Migration job | Separate privileged owner connection; never inject this into runtime apps. |
SSO_SECRET_ENCRYPTION_KEY_BASE64 | API, Worker | Each comma-separated encryption key decodes to exactly 32 bytes. Same ordered list on both services. Also protects telemetry credentials. |
CREDENTIAL_SECRET_ENCRYPTION_KEY_BASE64 | API, Worker | Exactly 32 bytes per key; same list on both. Protects broker passwords. |
MFA_TOTP_SECRET_ENCRYPTION_KEY_BASE64 | API | Exactly 32 bytes per encryption key. |
COMPLIANCE_SIGNING_KEY_BASE64 | API | Generate 32 bytes. Signing requires at least 32 decoded bytes; boot checks presence, not minimum signing length. Only the first entry signs and verifies. |
DATABASE_SSL_CA_BASE64 | Database clients, including operator jobs | Optional base64 PEM for a private database CA. |
These secret variables accept a <NAME>_FILE alternative pointing to a readable UTF-8 secret mount. Direct and file forms together are an error. File contents are trimmed at both ends; empty database input fails outside development/test. API-only keys are not Worker requirements. Bootstrap/migration need the database credential and applicable database trust, not all API encryption keys.
Use versionless Key Vault references in Azure, with application and migration identities restricted to their own secrets. Encryption keys are not interchangeable with signing keys. Follow Security and Secret Rotation before changing any key.
Network and authentication
| Variable | Code default | Production use |
|---|---|---|
API_PORT / HOST | 3000 / 0.0.0.0 | Reference Azure API target is 3000. |
API_UPSTREAM | Supplied by deployment | Web uses the internal API ingress FQDN without scheme or :3000. |
AUTH_MODE | oidc | Keep oidc; local is development header authentication and is rejected in production. Password sign-in is controlled in Admin. |
WEB_BASE_URL | http://localhost:5173 | Set the public HTTPS browser origin. |
CORS_ALLOWED_ORIGINS | http://localhost:5173 | Explicit comma-separated allowed origins; do not leave the development fallback. |
CSRF_PROTECTION_ENABLED | true | Keep enabled for cookie-authenticated changes. |
SSO_CALLBACK_BASE_URL | http://localhost:3000/api/v1/auth/sso/callback | Set the full same-origin HTTPS callback registered at the IdP. |
SSO_SESSION_STATE_TTL_SECONDS | 600 | Positive state/nonce/PKCE lifetime. |
SSO_JIT_PROVISIONING_ENABLED | false | Enable only with deliberate provider and access policy. |
MFA_TOTP_ISSUER / WEBAUTHN_RP_NAME | Particle Horizon | Message Operations | User-visible authenticator/passkey labels. |
WEBAUTHN_RP_ID | localhost | Set the browser hostname. |
WEBAUTHN_ORIGIN | Origin of WEB_BASE_URL | Set the exact HTTPS origin when needed. |
TRUST_PROXY | false | Reference Azure deployment sets true; keep the API internal. |
TRUST_PROXY_HOPS | 1 | Reference Azure path sets 3: Web ingress, Web nginx, API ingress. |
TRUST_PROXY_CIDRS | Loopback and private-network ranges | Narrow to actual trusted proxy subnets. Invalid or empty entries prevent startup. |
DATABASE_SSL_REJECT_UNAUTHORIZED | true | Keep certificate verification enabled. |
ALLOW_INSECURE_DATABASE | false | Keep false for the supported TLS database deployment. |
NODE_EXTRA_CA_CERTS | Unset | Optional mounted PEM extending Node HTTPS trust; set on both services when required. |
RATE_LIMIT_WINDOW_MS / RATE_LIMIT_MAX | 60000 / 300 | Global HTTP throttle window and request budget. |
The default trusted proxy ranges are 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, ::1/128, fc00::/7 and fe80::/10. Client-IP resolution stops at the first untrusted hop or the hop limit. Validate the live path before relying on service-account IP allowlists.
Production database clients reject insecure URL transport settings and apply an explicit TLS policy. URL ssl* and uselibpqcompat options are removed before connection; use the database CA setting above rather than relying on a URL sslrootcert file. Do not disable verification to fix a missing CA.
LOCAL_AUTH_ENABLED is a compatibility setting and does not control current password sign-in. OIDC_ISSUER_URL and OIDC_AUDIENCE configure the legacy direct bearer validation path, not multi-provider SSO. Configure browser providers through Admin.
Sessions and MFA
| Variable | Default | Meaning |
|---|---|---|
MFA_PRE_AUTH_TTL_SECONDS | 300 | Pre-authentication challenge lifetime. |
MFA_STEP_UP_TTL_SECONDS | 600 | Absolute recent-MFA window. |
MFA_MAX_ATTEMPTS | 5 | MFA attempt budget. |
LOGIN_MAX_ATTEMPTS | 10 | Password failure/in-flight budget; integer 1–1,000. |
LOGIN_ATTEMPT_WINDOW_SECONDS | 900 | Fixed password budget window; integer 1–3,600. |
SESSION_IDLE_TIMEOUT_SECONDS | 900 | Regular session idle limit. |
SESSION_ABSOLUTE_TIMEOUT_SECONDS | 7200 | Regular session absolute limit. |
ADMIN_SESSION_IDLE_TIMEOUT_SECONDS | 600 | Administrator idle limit. |
ADMIN_SESSION_ABSOLUTE_TIMEOUT_SECONDS | 3600 | Administrator absolute limit. |
SESSION_IDLE_WRITE_INTERVAL_SECONDS | 60 | Throttles persisted idle-deadline updates; sessions may expire slightly earlier. |
Broker and message controls
Configure endpoints, VPN and broker passwords through Manage Environments, not static broker environment variables. Set shared controls consistently on API and Worker.
| Variable | Default | Meaning |
|---|---|---|
SOLACE_ADAPTER | mock | Set real on both API and Worker for production brokers. |
SOLACE_CONNECT_TIMEOUT_MS | 10000 | Broker session connection timeout. |
SOLACE_CONNECT_RETRIES | 0 | Broker connection retries. |
SOLACE_BROWSE_TIMEOUT_MS | 60000 | Bounded queue browse time. |
SOLACE_PUBLISH_ACK_TIMEOUT_MS | 10000 | Guaranteed publish acknowledgement wait; timeout is an uncertain outcome. |
SOLACE_DISCONNECT_TIMEOUT_MS | 5000 | Bounded disconnect wait before disposal. |
SOLACE_MAX_PAYLOAD_BYTES | 5242880 | Per-message payload size bound. |
MESSAGE_SEARCH_DEFAULT_MAX_SCAN | 100000 | Default browse depth; hard ceiling 500,000. |
MESSAGE_PAYLOAD_LOOKUP_MAX_SCAN | 100000 | Browse depth when finding a selected payload again. |
MESSAGE_REF_TTL_SECONDS | 3600 | New reference lifetime; use the same value on API and Worker. |
MAX_BULK_MESSAGES | 500 | Positive bulk selection bound, including criteria/schedules. |
DISABLE_DELETE_OPERATIONS | false | Blocks deletes and moves. |
DISABLE_MOVE_OPERATIONS | false | Blocks moves. |
REQUIRE_CHANGE_REF_FOR_DELETE / REQUIRE_CHANGE_REF_FOR_MOVE | Parsed as true | Ineffective compatibility entries in v1.7.1; changing them does not disable the production change-reference requirement. |
PAYLOAD_MASKING_DISABLED_CATEGORIES | Empty | Comma-separated masking categories to disable; keep empty unless reviewed for your data. |
With NODE_ENV=production, direct move/delete always require a change reference. Every production schedule template also requires one, including resubmission. No change-reference variable disables these production gates.
Deletion/move containment must be configured on both services and followed by restart. Terraform uses shared disable_delete_operations and disable_move_operations inputs; per-component entries for these switches are rejected. Resubmission is unaffected by these two switches. An environment’s read-only setting blocks all three mutations. Already executing broker work is not rolled back. Queued attempts and later items recheck controls; failed jobs need a new submission after remediation. Schedule disable/delete remains possible.
Worker and queue
| Variable | Default | Meaning |
|---|---|---|
JOB_QUEUE_NAME | jobs | Must agree across API, Worker and migrator; exhausted delivery queue is <name>-dead. |
JOB_MAX_ATTEMPTS | 3 | Total delivery attempts including the first. |
JOB_BACKOFF_DELAY_MS | 5000 | Base exponential retry delay. |
JOB_EXPIRE_SECONDS | 900 | Stalled-job recovery interval. |
WORKER_CONCURRENCY | 4 | Concurrent jobs per Worker replica. |
POLLING_INTERVAL_SECONDS | 2 | Worker poll interval. |
QUEUE_BATCH_SIZE | 1 | Fetch batch size. |
SHUTDOWN_TIMEOUT_MS | 30000 | API/Worker job-queue graceful shutdown wait. |
WORKER_METRICS_PORT | 9090 | Worker health port; it is not a Prometheus metrics endpoint. |
SCHEDULE_TICK_ENABLED | true | Enables Worker schedule firing. |
SCHEDULE_TICK_INTERVAL_MS | 60000 | Schedule due-check cadence. |
RUN_MIGRATIONS_ON_BOOT | Deployment pins false | Compatibility marker; runtime never performs migrations. Use the dedicated job. |
Changing queue settings does not create missing queues: apply the matching dedicated migration configuration first. Never use the in-memory test queue driver in production. Job delivery retries do not imply that an uncertain publication is safe to repeat.
Background polling, retention and telemetry
| Variable | Default | Meaning |
|---|---|---|
ENVIRONMENT_HEARTBEAT_ENABLED | true | Fallback heartbeat enablement. |
ENVIRONMENT_HEARTBEAT_INTERVAL_MS | 30000 | Fallback heartbeat interval. |
ENVIRONMENT_HEARTBEAT_RETRIES | 0 | Heartbeat retries. |
QUEUE_INVENTORY_REFRESH_ENABLED | true | Fallback scheduled inventory enablement. |
QUEUE_INVENTORY_REFRESH_INTERVAL_MS | 86400000 | Fallback inventory interval. |
MESSAGE_REFS_RETENTION_DAYS | 30 | Reference age cap, independent of earlier per-row expiry. |
AUDIT_EVENTS_RETENTION_DAYS | 365 | Audit fallback; 0 retains indefinitely. Finite values below 90 are clamped. |
COMPLIANCE_EVIDENCE_RETENTION_DAYS | 90 | Expiry assigned to new evidence. |
RETENTION_SCHEDULER_ENABLED | true | API retention maintenance; automatically disabled in tests. |
COMPLIANCE_SCHEDULER_ENABLED | true | API weekly evidence generation/daily purge; disabled in tests. |
OTEL_TRACES_SAMPLER_RATIO | 1 | Startup trace sampling; saved settings replace it. |
OBSERVABILITY_RELOAD_INTERVAL_MS | 30000 | Saved telemetry reload; 0 disables automatic polling. |
SEMP Traffic overrides its deployment fallbacks after settings are saved. Admin → Settings overrides retention fallbacks; evidence changes apply to new bundles. Monitoring and Logging describes saved telemetry destinations and credentials.
Development compatibility and test-only switches are not a production configuration method. In particular, API and Worker refuse DISABLE_LICENSE_CHECK=true outside development/test.