Deploy on Vexlo Cloud in 60s (₹149/mo UPI) — India's First & Only Developer PaaS. Instant INR UPI & 17 global currencies ($5/mo).
Deploy Now
Bucket 3: Self-Hosted Open-Source Docker Templates7 min readVerified

Production n8n Queue Mode Docker Compose Template (PostgreSQL 16 + Redis 7 + Workers)

Complete copy-pasteable docker-compose.yml and .env template for self-hosting n8n in Queue Mode with PostgreSQL 16, Redis 7 BullMQ workers, webhook processors, and Traefik TLS.

TL;DR — Immediate Production Fix

Running n8n with its default SQLite database in a single container crashes under concurrent webhook bursts. To scale n8n in production on Docker Compose, enable Queue Mode (EXECUTIONS_MODE=queue) backed by PostgreSQL 16 and Redis 7. In Queue Mode, the main n8n instance handles UI and webhook ingestion, pushes job IDs into Redis via Bull, and dedicated n8n-worker containers execute workflows in parallel. Critically, every n8n-main and n8n-worker container MUST share the exact same N8N_ENCRYPTION_KEY environment variable, or workers will fail to decrypt stored OAuth/API credentials.

Verified Root Causes in Production Environments

  • Mismatched or Auto-Generated N8N_ENCRYPTION_KEY: If N8N_ENCRYPTION_KEY is not explicitly passed via environment variables, the worker container generates its own random key on boot and fails with 'Credentials could not be decrypted'.
  • Missing OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS=true: Without this flag in recent n8n releases, manual test runs from the editor UI still execute on the main process instead of Redis workers.
  • Unconfigured DB_POSTGRESDB Pool & Redis Healthchecks: Starting n8n before PostgreSQL and Redis are ready to accept connections causes startup crash loops.

1. Architecture of n8n Queue Mode (Main + Webhook + Redis Bull Workers)

In a standard single-container deployment, heavy data-transformation nodes or headless browser workflows block the Node.js event loop, causing incoming webhooks to time out and the editor UI to freeze. Enabling EXECUTIONS_MODE=queue decouples ingestion from execution.

When a webhook arrives at the main container, n8n creates an execution record in PostgreSQL, pushes the execution ID to Redis (`QUEUE_BULL_REDIS_HOST`), and a background worker container (`command: worker --concurrency=10`) pulls the job, decrypts your saved credentials using `N8N_ENCRYPTION_KEY`, runs the workflow, and writes the result back to PostgreSQL.

When scaling n8n in Queue Mode for production webhook automation, separating webhook ingestion from workflow execution prevents CPU-intensive code nodes or large JSON transformations from dropping incoming HTTP requests. You can further isolate traffic by deploying dedicated n8n-webhook containers (using command: webhook) behind Traefik load-balancer labels while keeping n8n-main restricted to internal editor UI traffic.

To prevent PostgreSQL disk exhaustion on high-volume automation servers, always configure EXECUTIONS_DATA_PRUNE=true, EXECUTIONS_DATA_MAX_AGE=168, and EXECUTIONS_DATA_PRUNE_MAX_COUNT=50000 in your shared environment anchor. Pair this with daily pg_dump snapshots to an off-site Cloudflare R2 bucket so your workflow definitions and encrypted credentials remain recoverable.

.env.example
ini
# Generate N8N_ENCRYPTION_KEY via: openssl rand -hex 32
N8N_ENCRYPTION_KEY=8f94a2b7c3d1e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c
N8N_HOST=n8n.vexlo.cloud
N8N_PROTOCOL=https
WEBHOOK_URL=https://n8n.vexlo.cloud/
GENERIC_TIMEZONE=Asia/Kolkata
TZ=Asia/Kolkata

# PostgreSQL 16 Credentials
POSTGRES_DB=n8n_prod
POSTGRES_USER=n8n_admin
POSTGRES_PASSWORD=super_secure_pg_password_2026

# Redis 7 Queue Configuration
QUEUE_BULL_REDIS_HOST=redis
QUEUE_BULL_REDIS_PORT=6379
QUEUE_BULL_REDIS_DB=0

2. Production docker-compose.yml With Shared Environment Anchor

Use a YAML anchor (`x-n8n-env: &n8n-env`) in your `docker-compose.yml` so the main UI node and all worker replicas automatically inherit the exact same database, Redis, and encryption variables without duplication errors.

Notice that `n8n-worker` overrides the container command with `worker --concurrency=10` and does not expose port 5678 to the reverse proxy.

docker-compose.yml
yaml
x-n8n-env: &n8n-env
  DB_TYPE: postgresdb
  DB_POSTGRESDB_HOST: postgres
  DB_POSTGRESDB_PORT: 5432
  DB_POSTGRESDB_DATABASE: ${POSTGRES_DB}
  DB_POSTGRESDB_USER: ${POSTGRES_USER}
  DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}
  EXECUTIONS_MODE: queue
  QUEUE_BULL_REDIS_HOST: ${QUEUE_BULL_REDIS_HOST}
  QUEUE_BULL_REDIS_PORT: ${QUEUE_BULL_REDIS_PORT}
  QUEUE_HEALTH_CHECK_ACTIVE: "true"
  OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS: "true"
  N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
  N8N_HOST: ${N8N_HOST}
  N8N_PROTOCOL: https
  WEBHOOK_URL: ${WEBHOOK_URL}
  GENERIC_TIMEZONE: ${GENERIC_TIMEZONE}
  TZ: ${TZ}
  EXECUTIONS_DATA_PRUNE: "true"
  EXECUTIONS_DATA_MAX_AGE: 168 # Prune execution logs older than 7 days

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes", "--maxmemory-policy", "noeviction"]
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  n8n-main:
    image: docker.n8n.io/n8nio/n8n:latest
    restart: unless-stopped
    environment:
      <<: *n8n-env
    ports:
      - "127.0.0.1:5678:5678"
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  n8n-worker:
    image: docker.n8n.io/n8nio/n8n:latest
    restart: unless-stopped
    command: worker --concurrency=10
    environment:
      <<: *n8n-env
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      n8n-main:
        condition: service_started

volumes:
  pg_data:
  redis_data:
  n8n_data:

3. Scaling Workers & Monitoring Queue Health Endpoints

Because `QUEUE_HEALTH_CHECK_ACTIVE=true` is enabled in the shared environment block, both `n8n-main` and `n8n-worker` expose `/healthz` and `/healthz/readiness` on port 5678. To scale horizontally during heavy webhook campaigns, run `docker compose up -d --scale n8n-worker=3`.

scale-n8n-workers.sh
bash
# Scale n8n worker containers to 3 parallel instances (30 concurrent executions)
docker compose up -d --scale n8n-worker=3

# Verify Redis Bull queue active jobs and worker connections
docker compose exec redis redis-cli CLIENT LIST | grep -i bull

Pre-Deployment Verification Checklist

  • Generate a 32-byte hex N8N_ENCRYPTION_KEY and inject it into both n8n-main and n8n-worker.
  • Set Redis --maxmemory-policy to noeviction so BullMQ job keys are never silently dropped under load.
  • Enable OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS=true so editor test runs also execute on workers.
  • Set EXECUTIONS_DATA_PRUNE=true and EXECUTIONS_DATA_MAX_AGE=168 to keep PostgreSQL disk usage bounded.
India's First & Only Developer PaaS

Deploy on Vexlo Cloud in 60s (₹149/mo UPI)

Automated Docker & Nixpacks builds, managed PostgreSQL/Redis, and AI Deployment Doctor. Instant INR UPI for India or USD/EUR/GBP across 17 global currencies.

Frequently Asked Questions

Why do n8n workers fail with 'Credentials could not be decrypted'?

The worker container does not have the exact same N8N_ENCRYPTION_KEY environment variable as the main n8n container that encrypted the credentials in PostgreSQL.

How much RAM do I need to self-host n8n in Queue Mode with Postgres and Redis?

A 2 vCPU / 4 GB RAM container stack on Vexlo Cloud (or Ubuntu VPS) comfortably runs n8n-main, two n8n-worker containers, PostgreSQL 16, and Redis 7.

Why should Redis use noeviction policy for n8n Queue Mode?

n8n uses Bull (Redis-backed job queues). If Redis evicts keys using volatile-lru or allkeys-lru when memory fills up, active workflow state and job locks are corrupted.

Primary Upstream References & Specifications

Keep Debugging

Related Guides

Browse all 30 guides →