Deployment
Environment Variables Reference Complete reference for all MPG_ configuration variables for both the Admin Backend and Main Backend.
All configuration uses the MPG_ prefix, loaded by Viper from environment variables or a .env file.
[!NOTE]
Both backends share many variable names (database, cache, logging, OTEL, rate limiting, encryption). Where the variable name is the same, it applies identically to both services unless noted.
Variable Type Required Default Description MPG_ENVstring No productionRuntime environment: dev, production, production-cloud
Variable Type Required Default Description MPG_DATABASE_URIstring Yes — MongoDB connection string (e.g., mongodb://user:pass@host:27017/) MPG_DATABASE_NAMEstring Yes — MongoDB database name MPG_DATABASE_MAX_POOL_SIZEint No 100Maximum connection pool size MPG_DATABASE_MIN_POOL_SIZEint No 10Minimum connection pool size MPG_DATABASE_MAX_CONN_IDLE_TIMEduration No 30mMaximum time a connection can be idle MPG_DATABASE_MAX_CONNECTINGint No 10Maximum concurrent connection attempts MPG_DATABASE_CONNECT_TIMEOUTduration No 10sConnection establishment timeout
Variable Type Required Default Description MPG_GARNET_URLstring No — Redis-compatible cache URL (e.g., redis://localhost:6379). If unset, in-memory cache is used.
Variable Type Required Default Description MPG_LOG_LEVELstring No errorLog level: debug, info, warn, error, fatal, panic MPG_LOG_FORMATstring No jsonLog format: json (structured) or text
Variable Type Required Default Description MPG_OTEL_ENABLEDbool No falseEnable OpenTelemetry tracing MPG_OTEL_EXPORTER_OTLP_PROTOCOLstring No — OTLP protocol: grpc or http/protobuf MPG_OTEL_EXPORTER_OTLP_ENDPOINTstring No — OTLP collector endpoint URL MPG_OTEL_EXPORTER_OTLP_HEADERSstring No — OTLP authentication headers (comma-separated key=value) MPG_OTEL_RESOURCE_ATTRIBUTESstring No — Resource attributes (e.g., service.name=payment-gateway) MPG_OTEL_EXPORTER_OTLP_INSECUREbool No falseSkip TLS verification for OTLP endpoint
Variable Type Required Default Description MPG_RATE_LIMIT_ENABLEDbool No trueEnable request rate limiting MPG_RATE_LIMIT_WINDOW_SIZEduration No 5mSliding window size MPG_RATE_LIMIT_MAX_REQUESTSint No 500Maximum requests per window MPG_RATE_LIMIT_REQUESTS_PER_MINint No 100Maximum requests per minute MPG_RATE_LIMIT_WHITELISTstring No 127.0.0.1,::1Comma-separated IPs to exempt from rate limiting
Variable Type Required Default Description MPG_SYSTEM_ENCRYPTION_KEYstring Yes — Hex-encoded symmetric key for encrypting KMS credentials. Admin backend requires exactly 32 bytes (64 hex characters). Main backend accepts 32+ bytes, but use 32 bytes to keep environments consistent. MPG_SYSTEM_SEARCH_HASH_KEYstring Yes — Hex-encoded HMAC key for deterministic searchable encryption. Exactly 32 bytes (64 hex characters).
Variable Type Required Default Description MPG_LICENSING_BYPASSbool No falseBypass license check. Only works if VERSION=dev. Never set in production.
Variable Type Required Default Description MPG_ADMIN_BACKEND_HOSTstring Yes — Bind address (e.g., 0.0.0.0) MPG_ADMIN_BACKEND_PORTint Yes — HTTP port (e.g., 8080) MPG_ADMIN_BACKEND_HTTPSbool No falseEnable TLS termination at the backend MPG_ADMIN_BACKEND_HTTPS_CERTstring No — Path to TLS certificate file MPG_ADMIN_BACKEND_HTTPS_KEYstring No — Path to TLS private key file MPG_ADMIN_BACKEND_DOMAINstring No — Public domain of the admin backend (optional; used for logging/metadata, not required by startup validation) MPG_ADMIN_FRONTEND_DOMAINstring Yes — Admin frontend domain for CORS allow-list (e.g., admin.yourcompany.com) MPG_MAIN_BACKEND_DOMAINstring Yes — Main backend public domain MPG_MAIN_FRONTEND_DOMAINstring Yes — Main frontend public domain MPG_MAIN_FRONTEND_SERVICEstring Yes — Internal service hostname for the main frontend (admin backend uses this for internal reachability checks) MPG_MAIN_FRONTEND_PORTstring Yes — Internal service port for the main frontend MPG_MAIN_BACKEND_SERVICEstring Yes — Internal service hostname for the main backend (admin backend uses this for internal reachability checks) MPG_MAIN_BACKEND_PORTstring Yes — Internal service port for the main backend
Variable Type Required Default Description MPG_SYSTEM_REFRESH_KEYstring Yes — Secret key for signing JWT refresh tokens (hex-encoded, exactly 64 bytes / 128 hex characters ) MPG_COOKIE_AUTH_KEYstring Yes — Session cookie authentication key (hex-encoded, 64 bytes recommended) MPG_COOKIE_ENCRYPTION_KEYstring Yes — Session cookie encryption key (hex-encoded, 32 bytes) MPG_WEBAUTHN_RPDISPLAYNAMEstring No — Display name shown in passkey dialogs (e.g., My Company Admin) MPG_WEBAUTHN_DEBUGbool No falseEnable verbose WebAuthn debug logging
Variable Type Required Default Description MPG_MAIN_WORKER_SERVICE_URLstring No — Internal URL of the worker service for PDF proxy requests MPG_LICENSING_AUTHORITY_URLstring No — Licensing Authority API base URL. Development commonly uses http://localhost:5173; staging/production should be HTTPS.
Variable Type Required Default Description MPG_MAIN_BACKEND_HOSTstring Yes — Bind address (e.g., 0.0.0.0) MPG_MAIN_BACKEND_PORTint Yes — HTTP port (e.g., 8081) MPG_MAIN_BACKEND_HTTPSbool No falseEnable TLS at backend MPG_MAIN_BACKEND_HTTPS_CERTstring No — TLS certificate path MPG_MAIN_BACKEND_HTTPS_KEYstring No — TLS private key path MPG_MAIN_BACKEND_DOMAINstring Yes — Public domain for this backend MPG_MAIN_FRONTEND_DOMAINstring Yes — Main frontend domain for CORS
Variable Type Required Default Description MPG_MAIN_WORKER_GOTENBERG_URLstring No http://localhost:3000URL of the Gotenberg PDF service MPG_MAIN_WORKER_TEMP_CACHE_DIRstring No OS temp dir + /pdf-cache Local directory for temporary PDF caching (defaults to the host OS temp directory). In container deployments this is commonly set explicitly (e.g. /tmp/pdf-cache). MPG_MAIN_WORKER_SERVICE_URLstring No — Internal URL where the worker HTTP server is reachable (used by the main API to proxy PDF requests) MPG_MAIN_WORKER_HOSTstring No 0.0.0.0Worker HTTP server bind address MPG_MAIN_WORKER_PORTint No 8090Worker HTTP server port MPG_MAIN_WORKER_CONCURRENCYint No 10Maximum concurrent PDF jobs MPG_MAIN_WORKER_SHUTDOWN_TIMEOUTint No 10Graceful shutdown timeout in seconds
Use openssl to generate cryptographically secure keys:
# 32-byte key (64 hex chars) — for SYSTEM_ENCRYPTION_KEY, SYSTEM_SEARCH_HASH_KEY, COOKIE_ENCRYPTION_KEY openssl rand -hex 32 # 64-byte key (128 hex chars) — for COOKIE_AUTH_KEY, SYSTEM_REFRESH_KEY openssl rand -hex 64
[!IMPORTANT]
Generate unique keys for each environment (development, staging, production). Never reuse keys across environments. Rotate keys if they are ever exposed.