Skip to content
BranchesTags

Repository files navigation

🚀 Scaling n8n with Docker Compose

English | فارسی

🇬🇧 English

This project is a scalable setup for n8n using the Queue Mode architecture.

System Architecture

                    ┌─────────────────────────────────────────────────────────────┐
                    │                         External                            │
                    │   Users ──────┐                                             │
                    │               ├──► Reverse Proxy (Nginx/Traefik)           │
                    │   Webhooks ───┘            │                                │
                    └────────────────────────────┼────────────────────────────────┘
                                                 │
                    ┌────────────────────────────┼────────────────────────────────┐
                    │                   n8n Stack│                                │
                    │                            ▼                                │
                    │              ┌─────────────────────────┐                    │
                    │              │      n8n Main           │                    │
                    │              │   (Editor + API)        │                    │
                    │              │      :5678              │                    │
                    │              └───────────┬─────────────┘                    │
                    │                          │                                  │
                    │         ┌────────────────┼────────────────┐                 │
                    │         ▼                ▼                ▼                 │
                    │   ┌──────────┐    ┌──────────┐    ┌──────────────┐          │
                    │   │ Worker 1 │    │ Worker N │    │Webhook Worker│          │
                    │   │          │    │          │    │    :5679     │          │
                    │   └────┬─────┘    └────┬─────┘    └──────┬───────┘          │
                    │        │               │                 │                  │
                    │        └───────────────┼─────────────────┘                  │
                    │                        ▼                                    │
                    │              ┌─────────────────────┐                        │
                    │              │       Redis         │                        │
                    │              │   (Message Queue)   │                        │
                    │              └─────────────────────┘                        │
                    │                        │                                    │
                    │                        ▼                                    │
                    │              ┌─────────────────────┐                        │
                    │              │     PgBouncer       │                        │
                    │              │ (Connection Pooler) │                        │
                    │              └──────────┬──────────┘                        │
                    │                         ▼                                   │
                    │              ┌─────────────────────┐                        │
                    │              │    PostgreSQL 17    │                        │
                    │              │     (Database)      │                        │
                    │              └─────────────────────┘                        │
                    └─────────────────────────────────────────────────────────────┘

📂 Project Structure

scalable-n8n-production-ready/
├── compose.yaml             # Main Docker Compose file
├── setup.sh                 # ✨ Automatic setup script
├── .env.example             # Sample configuration (all in one file)
├── .gitignore               # Files ignored by git
├── pgbouncer.ini.example    # PgBouncer sample configuration
├── userlist.txt.example     # PgBouncer users sample
├── init-data.sh             # DB user creation script
└── README.md                # This file

⚙️ Services

Service Image Purpose Port
PostgreSQL 17 postgres:17 Main database 5432 (internal)
PgBouncer edoburu/pgbouncer:v1.24.1-p0 Connection Pooling 6432 (internal)
Redis redis:7-alpine Message Queue 6379 (internal)
n8n Main ghcr.io/chosomeister/n8n:enterprise Editor/API 5678
Worker ghcr.io/chosomeister/n8n:enterprise Workflow execution -
Webhook Worker ghcr.io/chosomeister/n8n:enterprise Receive webhooks 5679

🔒 Security Settings

Environment Variables in .env-main:

Variable Description
NODE_ENV=production Production mode for Node.js
N8N_SECURE_COOKIE=true Send cookies only over HTTPS
N8N_ENCRYPTION_KEY Credential encryption (must be unique)
N8N_BLOCK_ENV_ACCESS_IN_NODE=true Prevent env access in Code nodes
N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true Check file permissions
QUEUE_BULL_REDIS_PASSWORD Redis password

Generating Secure Values:

# Encryption Key
openssl rand -hex 32

# Redis Password
openssl rand -base64 24

# Database Password
openssl rand -base64 24

🌐 Domain Settings

This setup requires two separate domains:

Domain Service Internal Port
https://n8n.yourdomain.com n8n Main (UI/API) 5678
https://n8n-webhook.yourdomain.com Webhook Worker 5679

In .env-main:

N8N_HOST=n8n.yourdomain.com
N8N_PROTOCOL=https
N8N_EDITOR_BASE_URL=https://n8n.yourdomain.com
WEBHOOK_URL=https://n8n-webhook.yourdomain.com

📊 Resource Limits

Service Memory Limit Memory Reserved
n8n Main 2GB 1GB
Worker 1GB 512MB
Webhook Worker 1GB 512MB

🔧 PgBouncer Configuration

pgbouncer.ini file:

Setting Value Description
pool_mode transaction Each query gets a new connection
max_client_conn 1000 Maximum connections from clients
default_pool_size 50 Concurrent connections to PostgreSQL
min_pool_size 5 Minimum open connections
reserve_pool_size 20 Emergency connections

userlist.txt file:

"n8n_user" "YOUR_DB_PASSWORD"

⚠️ For better security, use md5 hash: "n8n_user" "md5<hash>"

Generate md5: echo -n "YOUR_PASSWORD+n8n_user" | md5sum

▶️ Getting Started

Quick Start (Recommended)

git clone https://github.com/ChosoMeister/scalable-n8n-production-ready.git
cd scalable-n8n-production-ready
./setup.sh
docker compose up -d

The setup script automatically generates secure passwords and prepares all files.

Manual Setup

# 1. Clone
git clone https://github.com/ChosoMeister/scalable-n8n-production-ready.git
cd scalable-n8n-production-ready

# 2. Copy sample files
cp .env.example .env
cp pgbouncer.ini.example pgbouncer.ini
cp userlist.txt.example userlist.txt

# 3. Generate secure passwords and replace in files
nano .env           # All settings are here
nano pgbouncer.ini  # DB Password
nano userlist.txt   # DB Password

# 4. Start
docker compose up -d

Access

📌 Scaling Workers

# 3 workers
docker compose up -d --scale worker=3

# 5 workers
docker compose up -d --scale worker=5

Capacity Calculation:

Workers × Concurrency = Total Parallel Executions
5 workers × 10 concurrency = 50 parallel workflows

🔄 Execution Flow

1. Trigger/Webhook ─────► n8n Main
                              │
2.                     Create Job
                              │
3.                    ─────► Redis Queue
                              │
4.                     Worker picks job
                              │
5. Worker ◄───────────────────┘
      │
6.    └───► Get workflow from PostgreSQL
      │
7.    └───► Execute workflow
      │
8.    └───► Save results to PostgreSQL
      │
9.    └───► Notify Redis (complete)

📋 Execution Settings

In .env-main:

Variable Value Description
EXECUTIONS_TIMEOUT 3600 Maximum execution time (seconds)
EXECUTIONS_DATA_PRUNE true Auto-delete old executions
EXECUTIONS_DATA_MAX_AGE 168 Keep for 168 hours (7 days)
EXECUTIONS_DATA_SAVE_ON_ERROR all Save all errors
EXECUTIONS_DATA_SAVE_ON_SUCCESS all Save all successes

🕐 Timezone

GENERIC_TIMEZONE=Asia/Tehran
TZ=Asia/Tehran

Important for correct execution of Cron triggers and Schedule nodes

🔍 Useful Commands

# View status
docker compose ps

# Logs
docker compose logs -f n8n
docker compose logs -f worker
docker compose logs -f webhook-worker

# Stop
docker compose down

# Stop + delete volumes
docker compose down -v

# Restart a service
docker compose restart n8n

# Check config
docker compose config

⚠️ Important Notes

1. Reverse Proxy

This setup does not include a reverse proxy. You need to configure separately:

  • Nginx
  • Traefik
  • Caddy
  • HAProxy

2. SSL/HTTPS

Make sure to use HTTPS:

  • N8N_SECURE_COOKIE=true requires HTTPS
  • Webhooks are not secure without HTTPS

3. Backup

Backup the volumes:

  • db_storage - Database
  • n8n_storage - n8n files
# Backup database
docker compose exec postgres pg_dump -U lucas n8n > backup.sql

4. N8N_TRUSTED_PROXIES

If behind a reverse proxy:

N8N_TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

⚠️ Never use *!

📚 Resources

✅ Pre-Production Checklist

  • Unique N8N_ENCRYPTION_KEY is set
  • Strong REDIS_PASSWORD is set
  • Database passwords are strong
  • Real domains are configured
  • HTTPS is enabled
  • Reverse proxy is configured
  • You have a backup strategy
  • Monitoring is set up

🇮🇷 فارسی

این پروژه یک setup مقیاس‌پذیر برای n8n است که از معماری Queue Mode استفاده می‌کند.

معماری سیستم

                    ┌─────────────────────────────────────────────────────────────┐
                    │                         External                            │
                    │   Users ──────┐                                             │
                    │               ├──► Reverse Proxy (Nginx/Traefik)           │
                    │   Webhooks ───┘            │                                │
                    └────────────────────────────┼────────────────────────────────┘
                                                 │
                    ┌────────────────────────────┼────────────────────────────────┐
                    │                   n8n Stack│                                │
                    │                            ▼                                │
                    │              ┌─────────────────────────┐                    │
                    │              │      n8n Main           │                    │
                    │              │   (Editor + API)        │                    │
                    │              │      :5678              │                    │
                    │              └───────────┬─────────────┘                    │
                    │                          │                                  │
                    │         ┌────────────────┼────────────────┐                 │
                    │         ▼                ▼                ▼                 │
                    │   ┌──────────┐    ┌──────────┐    ┌──────────────┐          │
                    │   │ Worker 1 │    │ Worker N │    │Webhook Worker│          │
                    │   │          │    │          │    │    :5679     │          │
                    │   └────┬─────┘    └────┬─────┘    └──────┬───────┘          │
                    │        │               │                 │                  │
                    │        └───────────────┼─────────────────┘                  │
                    │                        ▼                                    │
                    │              ┌─────────────────────┐                        │
                    │              │       Redis         │                        │
                    │              │   (Message Queue)   │                        │
                    │              └─────────────────────┘                        │
                    │                        │                                    │
                    │                        ▼                                    │
                    │              ┌─────────────────────┐                        │
                    │              │     PgBouncer       │                        │
                    │              │ (Connection Pooler) │                        │
                    │              └──────────┬──────────┘                        │
                    │                         ▼                                   │
                    │              ┌─────────────────────┐                        │
                    │              │    PostgreSQL 17    │                        │
                    │              │     (Database)      │                        │
                    │              └─────────────────────┘                        │
                    └─────────────────────────────────────────────────────────────┘

📂 ساختار پروژه

scalable-n8n-production-ready/
├── compose.yaml             # Docker Compose اصلی
├── setup.sh                 # ✨ اسکریپت نصب خودکار
├── .env.example             # نمونه تنظیمات (همه در یک فایل)
├── .gitignore               # فایل‌های ignore شده در git
├── pgbouncer.ini.example    # نمونه تنظیمات PgBouncer
├── userlist.txt.example     # نمونه یوزرهای PgBouncer
├── init-data.sh             # اسکریپت ایجاد یوزر DB
└── README.md                # این فایل

⚙️ سرویس‌ها

سرویس Image وظیفه پورت
PostgreSQL 17 postgres:17 دیتابیس اصلی 5432 (internal)
PgBouncer edoburu/pgbouncer:v1.24.1-p0 Connection Pooling 6432 (internal)
Redis redis:7-alpine Message Queue 6379 (internal)
n8n Main ghcr.io/chosomeister/n8n:enterprise Editor/API 5678
Worker ghcr.io/chosomeister/n8n:enterprise اجرای workflows -
Webhook Worker ghcr.io/chosomeister/n8n:enterprise دریافت webhooks 5679

🔒 تنظیمات امنیتی

Environment Variables در .env-main:

Variable توضیح
NODE_ENV=production حالت production برای Node.js
N8N_SECURE_COOKIE=true ارسال cookies فقط روی HTTPS
N8N_ENCRYPTION_KEY رمزنگاری credentials (باید منحصر به فرد باشد)
N8N_BLOCK_ENV_ACCESS_IN_NODE=true جلوگیری از دسترسی به env در Code nodes
N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true بررسی دسترسی فایل‌ها
QUEUE_BULL_REDIS_PASSWORD پسورد Redis

تولید مقادیر امن:

# Encryption Key
openssl rand -hex 32

# Redis Password
openssl rand -base64 24

# Database Password
openssl rand -base64 24

🌐 تنظیمات دامنه

این setup نیاز به دو دامنه جداگانه دارد:

دامنه سرویس پورت داخلی
https://n8n.yourdomain.com n8n Main (UI/API) 5678
https://n8n-webhook.yourdomain.com Webhook Worker 5679

در .env-main:

N8N_HOST=n8n.yourdomain.com
N8N_PROTOCOL=https
N8N_EDITOR_BASE_URL=https://n8n.yourdomain.com
WEBHOOK_URL=https://n8n-webhook.yourdomain.com

📊 Resource Limits

سرویس Memory Limit Memory Reserved
n8n Main 2GB 1GB
Worker 1GB 512MB
Webhook Worker 1GB 512MB

🔧 تنظیمات PgBouncer

فایل pgbouncer.ini:

Setting مقدار توضیح
pool_mode transaction هر query اتصال جدید می‌گیرد
max_client_conn 1000 حداکثر اتصال از clients
default_pool_size 50 اتصالات همزمان به PostgreSQL
min_pool_size 5 حداقل اتصالات باز
reserve_pool_size 20 اتصالات اضطراری

فایل userlist.txt:

"n8n_user" "YOUR_DB_PASSWORD"

⚠️ برای امنیت بیشتر از md5 hash استفاده کنید: "n8n_user" "md5<hash>"

تولید md5: echo -n "YOUR_PASSWORD+n8n_user" | md5sum

▶️ راه‌اندازی

راه سریع (پیشنهادی)

git clone https://github.com/ChosoMeister/scalable-n8n-production-ready.git
cd scalable-n8n-production-ready
./setup.sh
docker compose up -d

اسکریپت setup به صورت خودکار پسوردهای امن تولید می‌کنه و همه فایل‌ها رو آماده می‌کنه.

راه دستی

# 1. Clone
git clone https://github.com/ChosoMeister/scalable-n8n-production-ready.git
cd scalable-n8n-production-ready

# 2. کپی فایل‌های نمونه
cp .env.example .env
cp pgbouncer.ini.example pgbouncer.ini
cp userlist.txt.example userlist.txt

# 3. تولید پسوردهای امن و جایگزینی در فایل‌ها
nano .env           # تمام تنظیمات اینجاست
nano pgbouncer.ini  # DB Password
nano userlist.txt   # DB Password

# 4. شروع
docker compose up -d

دسترسی

📌 Scale کردن Workers

# 3 worker
docker compose up -d --scale worker=3

# 5 worker
docker compose up -d --scale worker=5

محاسبه ظرفیت:

Workers × Concurrency = Total Parallel Executions
5 workers × 10 concurrency = 50 workflow همزمان

🔄 Workflow اجرا

1. Trigger/Webhook ─────► n8n Main
                              │
2.                     Create Job
                              │
3.                    ─────► Redis Queue
                              │
4.                     Worker picks job
                              │
5. Worker ◄───────────────────┘
      │
6.    └───► Get workflow from PostgreSQL
      │
7.    └───► Execute workflow
      │
8.    └───► Save results to PostgreSQL
      │
9.    └───► Notify Redis (complete)

📋 تنظیمات Execution

در .env-main:

Variable مقدار توضیح
EXECUTIONS_TIMEOUT 3600 حداکثر زمان اجرا (ثانیه)
EXECUTIONS_DATA_PRUNE true حذف خودکار execution های قدیمی
EXECUTIONS_DATA_MAX_AGE 168 نگهداری تا 168 ساعت (7 روز)
EXECUTIONS_DATA_SAVE_ON_ERROR all ذخیره همه خطاها
EXECUTIONS_DATA_SAVE_ON_SUCCESS all ذخیره همه موفقیت‌ها

🕐 Timezone

GENERIC_TIMEZONE=Asia/Tehran
TZ=Asia/Tehran

مهم برای اجرای صحیح Cron triggers و Schedule nodes

🔍 دستورات مفید

# مشاهده وضعیت
docker compose ps

# لاگ‌ها
docker compose logs -f n8n
docker compose logs -f worker
docker compose logs -f webhook-worker

# Stop
docker compose down

# Stop + حذف volumes
docker compose down -v

# Restart یک سرویس
docker compose restart n8n

# بررسی config
docker compose config

⚠️ نکات مهم

1. Reverse Proxy

این setup شامل reverse proxy نیست. باید جداگانه تنظیم کنید:

  • Nginx
  • Traefik
  • Caddy
  • HAProxy

2. SSL/HTTPS

حتماً از HTTPS استفاده کنید:

  • N8N_SECURE_COOKIE=true نیاز به HTTPS دارد
  • Webhooks امن نیستند بدون HTTPS

3. Backup

Volume ها را backup کنید:

  • db_storage - دیتابیس
  • n8n_storage - فایل‌های n8n
# Backup database
docker compose exec postgres pg_dump -U lucas n8n > backup.sql

4. N8N_TRUSTED_PROXIES

اگر پشت reverse proxy هستید:

N8N_TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

⚠️ هرگز از * استفاده نکنید!

📚 منابع

✅ Checklist قبل از Production

  • N8N_ENCRYPTION_KEY منحصر به فرد تنظیم شده
  • REDIS_PASSWORD قوی تنظیم شده
  • پسوردهای دیتابیس قوی هستند
  • دامنه‌های واقعی تنظیم شده
  • HTTPS فعال است
  • Reverse proxy تنظیم شده
  • Backup strategy دارید
  • Monitoring تنظیم شده

About

Production-ready n8n Docker Compose stack with Queue Mode, Redis, PostgreSQL, PgBouncer, dedicated webhook worker, and horizontal worker scaling.

Topics

automationdevopsdockerdocker-composehorizontal-scalinginfrastructuren8nn8n-dockernginxpgbouncerpostgrespostgresqlproduction-readyqueue-moderedisreverse-proxyself-hostedtraefikwebhook-workerworkflow-automation

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages