Configuration

Configuring the Payment Gateway correctly ensures secure and reliable operation. This guide focuses on database security and worker cache optimization.

MongoDB TLS Encryption

MongoDB TLS becomes active when MONGO_TLS_ENABLED=true and certificate files exist. Both the bash and PowerShell secrets generators default to MONGO_TLS_ENABLED=true when the flag is not set. Generate certificates and keep TLS enabled before relying on it in production.

[!NOTE] Podman: the shipped Quadlet unit starts mongod with requireTLS when certificates are mounted under the Mongo config directory, regardless of the env flag. On Podman, MONGO_TLS_ENABLED in .env-mongo primarily controls whether secret-generation scripts build TLS connection strings that match the running server.

Quick TLS Setup

Generate Certificates (This is a one-time setup on the host):

# Linux/macOS
./scripts/generate-mongo-certs.sh

# Windows (PowerShell)
.\scripts\generate-mongo-certs.ps1

Enable TLS in your environment:

For Docker Compose:

export MONGO_TLS_ENABLED=true
cd docker-compose && ./deploy.sh

For Podman:

echo "MONGO_TLS_ENABLED=true" >> ~/.config/payment-gateway-deploy/.env-mongo
cd podman && ./deploy.sh

Regenerate Secrets: This step injects the TLS connection strings into your applications:
```
export MONGO_TLS_ENABLED=true
./scripts/generate-secrets.sh --force
```

Only disable MongoDB TLS in a controlled non-production environment. Production deployments should keep database TLS enabled.

Worker Configuration (PDF Generation)

The payment-gateway-main-worker handles PDF generation using Gotenberg via HTTP.

Key environment variables for configuring the worker in Podman environment files or your unified .env (Docker Compose) include:

Variable	Description	Default
`MPG_MAIN_WORKER_PORT`	HTTP port serving cached PDFs	`8090`
`MPG_MAIN_WORKER_CONCURRENCY`	Maximum concurrent PDF background jobs	`10`
`MPG_MAIN_WORKER_GOTENBERG_URL`	Gotenberg API endpoint	`http://gotenberg:3000` in deployment templates; the backend code default is `http://localhost:3000` when unset outside deploy configs
`MPG_MAIN_WORKER_TEMP_CACHE_DIR`	Temp directory for PDF caching (24h cleanup).	`/tmp/pdf-cache`

Best Practice: Deploy configs should mount MPG_MAIN_WORKER_TEMP_CACHE_DIR as a tmpfs volume with mode 1777 for performance and automatic clearing.

PDF Storage Configuration

Out of the box, generated PDFs and e-invoice artifacts are served from the worker's temporary cache and cleaned up automatically. Treat this as an operational delivery cache, not as your legal archive.

Some releases expose organization-level PDF storage settings in Settings > Invoicing > PDF Storage. Before depending on those settings for durable retention, verify the exact storage provider in your release by generating, downloading, restarting the worker, and downloading the same issued document again. Keep MongoDB backups and your own accounting archive in place regardless of PDF cache behavior.

Backup and Recovery

For GDPR-oriented backup policy, manual on-demand backups, and manual restore runbooks, see:

Configuration Requirements