ConfigurationCopy Anchor Link

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

MongoDB TLS EncryptionCopy Anchor Link

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 SetupCopy Anchor Link

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

   Copy Text

   # Linux/macOS
   ./scripts/generate-mongo-certs.sh
   
   # Windows (PowerShell)
   .\scripts\generate-mongo-certs.ps1

2. Enable TLS in your environment:

   • For Docker Compose:

     Copy Text

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

   • For Podman:

     Copy Text

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

3. Regenerate Secrets: This step injects the TLS connection strings into your applications:

   Copy Text

   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)Copy Anchor Link

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:

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 ConfigurationCopy Anchor Link

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.

Configure private Amazon S3 or S3-compatible storage under Settings > Invoicing > PDF Storage. Azure Blob and Google Cloud Storage are not implemented; enabled unsupported providers and failed cloud uploads stop generation rather than silently using the cache. Saving validates configuration, not connectivity.

Follow the PDF Storage guide to configure credentials, verify generation and downloads across a worker restart, and understand the impact of changing storage on older documents. Keep MongoDB backups and your own accounting archive regardless of PDF cache behavior. Keep the internal worker HTTP endpoint private; public access must go through the application's authorized document routes.

Reminder Worker RolloutCopy Anchor Link

Upgrade the application and all active SMTP workers together. Drain or stop older SMTP workers before allowing the new workers to process automatic reminders and escalations. Older workers do not honor the durable send-attempt guard and can resend an attempt that a new worker has held for review. A rollback to an older worker does not preserve the no-automatic-redelivery behavior.

Monitor worker logs for automatic retry held. A hold can indicate an unconfirmed SMTP attempt or missing delivery evidence after retention. Compare SMTP provider evidence before any manual follow-up; do not clear attempt markers or reset jobs to bypass the hold. A crash before SMTP, or an old interrupted enqueue whose delivery evidence is unavailable, can conservatively hold an unsent email. See reminder delivery status.

Backup and RecoveryCopy Anchor Link

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

• Backup & Recovery (GDPR)
• Data Processing & Encryption