payment-gateway.app Docs
Deployment

Environment Variables Reference

Complete reference for all MPG_ configuration variables for both the Admin Backend and Main Backend.

Environment Variables Reference

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.

Shared Variables (Both Backends)

Server

VariableTypeRequiredDefaultDescription
MPG_ENVstringNoproductionRuntime environment: dev, production, production-cloud

Database (MongoDB)

VariableTypeRequiredDefaultDescription
MPG_DATABASE_URIstringYes—MongoDB connection string. Bundled MongoDB uses mongodb://user:pass@mongo:27017/database?authSource=database&replicaSet=rs0; customer-supplied Atlas URIs remain unchanged.
MPG_DATABASE_NAMEstringYes—MongoDB database name
MPG_DATABASE_MAX_POOL_SIZEintNo100Maximum connection pool size
MPG_DATABASE_MIN_POOL_SIZEintNo10Minimum connection pool size
MPG_DATABASE_MAX_CONN_IDLE_TIMEdurationNo30mMaximum time a connection can be idle
MPG_DATABASE_MAX_CONNECTINGintNo10Maximum concurrent connection attempts
MPG_DATABASE_CONNECT_TIMEOUTdurationNo10sConnection establishment timeout

Cache (Redis / Garnet)

VariableTypeRequiredDefaultDescription
MPG_GARNET_URLstringNo—Redis-compatible cache URL (e.g., redis://localhost:6379). If unset, in-memory cache is used.

Logging

VariableTypeRequiredDefaultDescription
MPG_LOG_LEVELstringNoerrorLog level: debug, info, warn, error, fatal, panic
MPG_LOG_FORMATstringNojsonLog format: json (structured) or text

OpenTelemetry (Tracing)

VariableTypeRequiredDefaultDescription
MPG_OTEL_ENABLEDboolNofalseEnable OpenTelemetry tracing
MPG_OTEL_EXPORTER_OTLP_PROTOCOLstringNo—OTLP protocol: grpc or http/protobuf
MPG_OTEL_EXPORTER_OTLP_ENDPOINTstringNo—OTLP collector endpoint URL
MPG_OTEL_EXPORTER_OTLP_HEADERSstringNo—OTLP authentication headers (comma-separated key=value)
MPG_OTEL_RESOURCE_ATTRIBUTESstringNo—Resource attributes (e.g., service.name=payment-gateway)
MPG_OTEL_EXPORTER_OTLP_INSECUREboolNofalseSkip TLS verification for OTLP endpoint

Rate Limiting

VariableTypeRequiredDefaultDescription
MPG_RATE_LIMIT_ENABLEDboolNotrueEnable request rate limiting
MPG_RATE_LIMIT_WINDOW_SIZEdurationNo5mRequest window size
MPG_RATE_LIMIT_MAX_REQUESTSintNo500Maximum requests per window
MPG_RATE_LIMIT_REQUESTS_PER_MINintNo100Maximum requests per minute
MPG_RATE_LIMIT_WHITELISTstringNo127.0.0.1,::1Comma-separated IPs to exempt from rate limiting

In v6.0.0, POST /api/v1/auth/refresh-token and GET /api/v1/auth/login/check are excluded from the ordinary Admin API request budget. Each has its own per-IP fixed-window counter. Refresh allows 20 requests per 10 minutes; login checks use MPG_RATE_LIMIT_MAX_REQUESTS and MPG_RATE_LIMIT_WINDOW_SIZE (defaults: 500 requests per 5 minutes). Exhausted counters return 429 with Retry-After; an unavailable rate-limit store returns 503 with Retry-After: 1.

MPG_RATE_LIMIT_ENABLED controls whether these authentication limits are active. The refresh maximum/window are fixed, and neither authentication budget uses MPG_RATE_LIMIT_WHITELIST. There is no shared deployment-wide refresh budget. Only the explicit refresh endpoint rotates refresh credentials; see session recovery.

Security & Network Trust

VariableTypeRequiredDefaultDescription
MPG_SECURITY_TRUSTED_PROXIESstringNointernal container rangesComma-separated CIDRs/IPs of trusted reverse proxies. Client-IP forwarding headers (X-Real-IP, X-Forwarded-For) are honoured only when the immediate peer matches one of these entries; otherwise the raw connection IP is used for rate limiting and session IP binding. Provider-agnostic — does not require Cloudflare. Set to your load balancer's CIDR(s) if you front the stack with an external proxy. Both backends.
MPG_INTERNAL_HEALTH_TOKENstringNo— (source-IP check only)Shared secret required, in addition to the private/loopback source check, for the /internal/health deep endpoint. Behind a proxy the connection IP is the proxy, so this token is the real access gate. Set in production. Both backends.
MPG_IPN_ALLOW_PRIVATE_TARGETSboolNofalseAllow IPN webhook delivery to private/loopback/link-local targets (SSRF guard). Keep false in production. Main backend only.
MPG_SECURITY_ALLOW_PRIVATE_SMTPboolNofalseAllow SMTP test/send to dial private/loopback/link-local hosts (SSRF guard; cloud-metadata endpoints stay blocked regardless). Keep false in production. Admin backend only.

Note: The bundled Caddy reverse proxy forwards an authoritative X-Real-IP derived from its own trusted-proxy configuration, so the backends only need to trust the proxy hop (MPG_SECURITY_TRUSTED_PROXIES defaults to the internal container networks). Cloudflare is not required — any reverse proxy, or no proxy at all, is supported.

Encryption

VariableTypeRequiredDefaultDescription
MPG_SYSTEM_ENCRYPTION_KEYstringYes—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_KEYstringYes—Hex-encoded HMAC key for deterministic searchable encryption. Exactly 32 bytes (64 hex characters).

Admin Backend Variables

Server

VariableTypeRequiredDefaultDescription
MPG_ADMIN_BACKEND_HOSTstringYes—Bind address (e.g., 0.0.0.0)
MPG_ADMIN_BACKEND_PORTintYes—HTTP port (e.g., 8080)
MPG_ADMIN_BACKEND_HTTPSboolNofalseEnable TLS termination at the backend
MPG_ADMIN_BACKEND_HTTPS_CERTstringNo—Path to TLS certificate file
MPG_ADMIN_BACKEND_HTTPS_KEYstringNo—Path to TLS private key file
MPG_ADMIN_BACKEND_DOMAINstringNo—Public domain of the admin backend (optional; used for logging/metadata, not required by startup validation)
MPG_ADMIN_FRONTEND_DOMAINstringYes—Admin frontend domain for CORS allow-list (e.g., admin.yourcompany.com)
MPG_MAIN_BACKEND_DOMAINstringYes—Main backend public domain
MPG_MAIN_FRONTEND_DOMAINstringYes—Main frontend public domain
MPG_MAIN_FRONTEND_SERVICEstringYes—Deployment-managed service hostname for the main frontend
MPG_MAIN_FRONTEND_PORTstringYes—Deployment-managed service port for the main frontend
MPG_MAIN_BACKEND_SERVICEstringYes—Deployment-managed service hostname for the main backend
MPG_MAIN_BACKEND_PORTstringYes—Deployment-managed service port for the main backend

Authentication

VariableTypeRequiredDefaultDescription
MPG_SYSTEM_REFRESH_KEYstringYes—Secret key for signing JWT refresh tokens (hex-encoded, exactly 64 bytes / 128 hex characters)
MPG_COOKIE_AUTH_KEYstringYes—Session cookie authentication key (hex-encoded, 64 bytes recommended)
MPG_COOKIE_ENCRYPTION_KEYstringYes—Session cookie encryption key (hex-encoded, 32 bytes)
MPG_WEBAUTHN_RPDISPLAYNAMEstringNo—Display name shown in passkey dialogs (e.g., My Company Admin)
MPG_WEBAUTHN_DEBUGboolNofalseEnable verbose WebAuthn debug logging

External Services

VariableTypeRequiredDefaultDescription
MPG_MAIN_WORKER_SERVICE_URLstringNo—Internal URL of the worker service for PDF proxy requests
MPG_LICENSING_AUTHORITY_URLstringNo—Trusted vendor licensing endpoint. Leave unset for official deployments unless support instructs otherwise.

Main Backend Variables

Server

VariableTypeRequiredDefaultDescription
MPG_MAIN_BACKEND_HOSTstringYes—Bind address (e.g., 0.0.0.0)
MPG_MAIN_BACKEND_PORTintYes—HTTP port (e.g., 8081)
MPG_MAIN_BACKEND_HTTPSboolNofalseEnable TLS at backend
MPG_MAIN_BACKEND_HTTPS_CERTstringNo—TLS certificate path
MPG_MAIN_BACKEND_HTTPS_KEYstringNo—TLS private key path
MPG_MAIN_BACKEND_DOMAINstringYes—Public domain for this backend
MPG_MAIN_FRONTEND_DOMAINstringYes—Main frontend domain for CORS

Worker (PDF Generation)

VariableTypeRequiredDefaultDescription
MPG_MAIN_WORKER_GOTENBERG_URLstringNohttp://localhost:3000URL of the Gotenberg PDF service; deployment templates set this to the internal Gotenberg service.
MPG_MAIN_WORKER_TEMP_CACHE_DIRstringNoOS temp dir + /pdf-cacheLocal 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_URLstringNo—Internal URL where the worker HTTP server is reachable (used by the main API to proxy PDF requests)
MPG_MAIN_WORKER_HOSTstringNo0.0.0.0Worker HTTP server bind address
MPG_MAIN_WORKER_PORTintNo8090Worker HTTP server port
MPG_MAIN_WORKER_CONCURRENCYintNo10Maximum concurrent PDF jobs
MPG_MAIN_WORKER_SHUTDOWN_TIMEOUTintNo10Graceful shutdown timeout in seconds

Generating Secure Keys

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.

Docker Compose Deployment

Deploying using traditional Docker Compose on any operating system.

Evidence & Audit Checklist

Operational checklist for proving data-protection controls in self-hosted environments.

On this page

Environment Variables ReferenceShared Variables (Both Backends)ServerDatabase (MongoDB)Cache (Redis / Garnet)LoggingOpenTelemetry (Tracing)Rate LimitingSecurity & Network TrustEncryptionAdmin Backend VariablesServerAuthenticationExternal ServicesMain Backend VariablesServerWorker (PDF Generation)Generating Secure Keys