n8n Hosting & Configuration
Deploy and configure self-hosted n8n instances.
Quick Start
Docker (Recommended)
docker run -d
--name n8n
-p 5678:5678
-v n8n_data:/home/node/.n8n
-e N8N_BASIC_AUTH_ACTIVE=true
-e N8N_BASIC_AUTH_USER=admin
-e N8N_BASIC_AUTH_PASSWORD=secure-password
n8nio/n8n
Docker Compose (Production)
version: '3.8'
services: n8n: image: n8nio/n8n:latest restart: always ports: - "5678:5678" environment: - N8N_HOST=n8n.yourdomain.com - N8N_PORT=5678 - N8N_PROTOCOL=https - WEBHOOK_URL=https://n8n.yourdomain.com/ - GENERIC_TIMEZONE=America/New_York - TZ=America/New_York - DB_TYPE=postgresdb - DB_POSTGRESDB_HOST=postgres - DB_POSTGRESDB_DATABASE=n8n - DB_POSTGRESDB_USER=n8n - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD} - N8N_ENCRYPTION_KEY=${ENCRYPTION_KEY} - N8N_USER_MANAGEMENT_JWT_SECRET=${JWT_SECRET} volumes: - n8n_data:/home/node/.n8n depends_on: - postgres
postgres: image: postgres:15 restart: always environment: - POSTGRES_USER=n8n - POSTGRES_PASSWORD=${POSTGRES_PASSWORD} - POSTGRES_DB=n8n volumes: - postgres_data:/var/lib/postgresql/data
volumes: n8n_data: postgres_data:
NPM Installation
npm install n8n -g n8n start
Environment Variables
Core Settings
Instance Configuration
N8N_HOST=localhost # Hostname N8N_PORT=5678 # Port N8N_PROTOCOL=https # http or https WEBHOOK_URL=https://n8n.example.com/ # Public webhook URL
Timezone
GENERIC_TIMEZONE=America/New_York TZ=America/New_York
Encryption (REQUIRED for production)
N8N_ENCRYPTION_KEY=your-32-char-encryption-key
User Management
N8N_USER_MANAGEMENT_JWT_SECRET=your-jwt-secret N8N_USER_MANAGEMENT_DISABLED=false
Database Configuration
SQLite (Default)
Uses ~/.n8n/database.sqlite by default
DB_TYPE=sqlite DB_SQLITE_DATABASE=/home/node/.n8n/database.sqlite
PostgreSQL (Recommended for Production)
DB_TYPE=postgresdb DB_POSTGRESDB_HOST=localhost DB_POSTGRESDB_PORT=5432 DB_POSTGRESDB_DATABASE=n8n DB_POSTGRESDB_USER=n8n DB_POSTGRESDB_PASSWORD=secure-password DB_POSTGRESDB_SCHEMA=public
Connection pooling
DB_POSTGRESDB_POOL_SIZE=10
MySQL/MariaDB
DB_TYPE=mysqldb DB_MYSQLDB_HOST=localhost DB_MYSQLDB_PORT=3306 DB_MYSQLDB_DATABASE=n8n DB_MYSQLDB_USER=n8n DB_MYSQLDB_PASSWORD=secure-password
Execution Settings
Execution mode
EXECUTIONS_MODE=queue # regular or queue
Process settings
EXECUTIONS_PROCESS=main # main or own (separate process) EXECUTIONS_TIMEOUT=3600 # Timeout in seconds EXECUTIONS_TIMEOUT_MAX=7200 # Max timeout
Data retention
EXECUTIONS_DATA_SAVE_ON_ERROR=all EXECUTIONS_DATA_SAVE_ON_SUCCESS=none # Save storage EXECUTIONS_DATA_SAVE_ON_PROGRESS=false EXECUTIONS_DATA_SAVE_MANUAL_EXECUTIONS=true EXECUTIONS_DATA_PRUNE=true EXECUTIONS_DATA_MAX_AGE=336 # Hours (14 days)
Queue Mode (Redis)
EXECUTIONS_MODE=queue QUEUE_BULL_REDIS_HOST=localhost QUEUE_BULL_REDIS_PORT=6379 QUEUE_BULL_REDIS_PASSWORD=redis-password QUEUE_BULL_REDIS_DB=0
Worker settings
QUEUE_BULL_REDIS_TIMEOUT_THRESHOLD=10000 QUEUE_HEALTH_CHECK_ACTIVE=true
Authentication
Basic Auth
N8N_BASIC_AUTH_ACTIVE=true N8N_BASIC_AUTH_USER=admin N8N_BASIC_AUTH_PASSWORD=secure-password
JWT Auth
N8N_JWT_AUTH_ACTIVE=true N8N_JWT_AUTH_HEADER=Authorization N8N_JWKS_URI=https://your-auth-provider/.well-known/jwks.json
LDAP (Enterprise)
N8N_AUTH_LDAP_ENABLED=true N8N_AUTH_LDAP_URL=ldap://ldap.example.com:389 N8N_AUTH_LDAP_BIND_DN=cn=admin,dc=example,dc=com N8N_AUTH_LDAP_BIND_PASSWORD=ldap-password
Security Settings
HTTPS
N8N_SSL_KEY=/path/to/private.key N8N_SSL_CERT=/path/to/certificate.crt
Security headers
N8N_SECURE_COOKIE=true
IP restrictions
N8N_EDITOR_BASE_URL=https://n8n.example.com N8N_BLOCK_ENV_ACCESS_IN_NODE=true
Endpoint restrictions
N8N_METRICS=true N8N_METRICS_PREFIX=n8n_
Logging
Log level
N8N_LOG_LEVEL=info # debug, info, warn, error N8N_LOG_OUTPUT=console # console or file N8N_LOG_FILE_LOCATION=/var/log/n8n/
Log streaming (Enterprise)
N8N_EXTERNAL_STORAGE_ENABLED=true
Email (SMTP)
N8N_EMAIL_MODE=smtp N8N_SMTP_HOST=smtp.example.com N8N_SMTP_PORT=587 N8N_SMTP_USER=n8n@example.com N8N_SMTP_PASS=smtp-password N8N_SMTP_SSL=true N8N_SMTP_SENDER=n8n@example.com
Scaling & High Availability
Horizontal Scaling with Queue Mode
docker-compose.yml
version: '3.8'
services: n8n-main: image: n8nio/n8n environment: - EXECUTIONS_MODE=queue - QUEUE_BULL_REDIS_HOST=redis command: n8n start # ... other config
n8n-worker-1: image: n8nio/n8n environment: - EXECUTIONS_MODE=queue - QUEUE_BULL_REDIS_HOST=redis command: n8n worker deploy: replicas: 3
redis: image: redis:alpine volumes: - redis_data:/data
postgres: image: postgres:15 # ... config
volumes: redis_data:
Kubernetes Deployment
apiVersion: apps/v1 kind: Deployment metadata: name: n8n spec: replicas: 1 selector: matchLabels: app: n8n template: metadata: labels: app: n8n spec: containers: - name: n8n image: n8nio/n8n:latest ports: - containerPort: 5678 env: - name: DB_TYPE value: postgresdb - name: DB_POSTGRESDB_HOST valueFrom: secretKeyRef: name: n8n-secrets key: db-host envFrom: - secretRef: name: n8n-secrets volumeMounts: - name: data mountPath: /home/node/.n8n volumes: - name: data persistentVolumeClaim: claimName: n8n-pvc
apiVersion: v1 kind: Service metadata: name: n8n spec: selector: app: n8n ports:
- port: 5678 targetPort: 5678 type: ClusterIP
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: n8n annotations: cert-manager.io/cluster-issuer: letsencrypt spec: tls:
- hosts:
- n8n.example.com secretName: n8n-tls rules:
- host: n8n.example.com
http:
paths:
- path: / pathType: Prefix backend: service: name: n8n port: number: 5678
Worker Configuration
Main instance (editor + webhooks)
n8n start
Worker instances (execution only)
n8n worker --concurrency=10
Webhook processor
n8n webhook
Reverse Proxy
Nginx Configuration
server { listen 443 ssl http2; server_name n8n.example.com;
ssl_certificate /etc/letsencrypt/live/n8n.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/n8n.example.com/privkey.pem;
location / {
proxy_pass http://localhost:5678;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# WebSocket support
proxy_read_timeout 86400;
proxy_send_timeout 86400;
}
# Increase body size for file uploads
client_max_body_size 100M;
}
Traefik (Docker)
services:
n8n:
image: n8nio/n8n
labels:
- "traefik.enable=true"
- "traefik.http.routers.n8n.rule=Host(n8n.example.com)"
- "traefik.http.routers.n8n.entrypoints=websecure"
- "traefik.http.routers.n8n.tls.certresolver=letsencrypt"
- "traefik.http.services.n8n.loadbalancer.server.port=5678"
External Secrets Management
HashiCorp Vault
Enable external secrets
N8N_EXTERNAL_SECRETS_ENABLED=true N8N_EXTERNAL_SECRETS_BACKEND=vault
Vault configuration
VAULT_ADDR=https://vault.example.com VAULT_TOKEN=your-vault-token VAULT_MOUNT_PATH=secret
AWS Secrets Manager
N8N_EXTERNAL_SECRETS_ENABLED=true N8N_EXTERNAL_SECRETS_BACKEND=aws
AWS_REGION=us-east-1 AWS_ACCESS_KEY_ID=your-access-key AWS_SECRET_ACCESS_KEY=your-secret-key
Environment-based Secrets
Reference in n8n as: {{ $env.MY_SECRET }}
MY_SECRET=secret-value API_KEY=api-key-value
Backup & Recovery
Database Backup
PostgreSQL backup
pg_dump -h localhost -U n8n -d n8n > backup.sql
Restore
psql -h localhost -U n8n -d n8n < backup.sql
File System Backup
Backup n8n data directory
tar -czf n8n-backup.tar.gz /home/node/.n8n
Includes:
- credentials (encrypted)
- workflows (if file-based)
- settings
Export/Import Workflows
Export all workflows via API
curl -X GET "http://localhost:5678/api/v1/workflows"
-H "X-N8N-API-KEY: $API_KEY" > workflows.json
Import workflow
curl -X POST "http://localhost:5678/api/v1/workflows"
-H "X-N8N-API-KEY: $API_KEY"
-H "Content-Type: application/json"
-d @workflow.json
Enterprise Features
Source Control (Git)
Enable source control
N8N_SOURCECONTROL_ENABLED=true N8N_SOURCECONTROL_DEFAULT_BRANCH=main
Environments
Development
N8N_ENVIRONMENT=development
Staging
N8N_ENVIRONMENT=staging
Production
N8N_ENVIRONMENT=production
Log Streaming
N8N_LOG_STREAMING_ENABLED=true N8N_LOG_STREAMING_DESTINATION=https://logs.example.com
RBAC (Role-Based Access Control)
-
Owner: Full access
-
Admin: Manage users and settings
-
Member: Execute and edit workflows
-
Viewer: Read-only access
SSO/SAML
N8N_AUTH_SAML_ENABLED=true N8N_AUTH_SAML_METADATA_URL=https://idp.example.com/metadata
Monitoring
Health Check
Liveness
GET /healthz
Readiness
GET /healthz/readiness
Metrics (Prometheus)
N8N_METRICS=true N8N_METRICS_PREFIX=n8n_
Scrape endpoint
GET /metrics
Example metrics:
-
n8n_workflow_executions_total
-
n8n_workflow_execution_duration_seconds
-
n8n_active_workflows
Grafana Dashboard
{ "panels": [ { "title": "Executions per minute", "targets": [{ "expr": "rate(n8n_workflow_executions_total[1m])" }] }, { "title": "Execution duration", "targets": [{ "expr": "histogram_quantile(0.95, n8n_workflow_execution_duration_seconds_bucket)" }] } ] }
Troubleshooting
Common Issues
Webhook Not Accessible
Check WEBHOOK_URL is set correctly
WEBHOOK_URL=https://your-public-url/
Ensure port is exposed
-p 5678:5678
Database Connection Failed
Test PostgreSQL connection
psql -h $DB_POSTGRESDB_HOST -U $DB_POSTGRESDB_USER -d $DB_POSTGRESDB_DATABASE
Check credentials and network
Memory Issues
Increase Node.js memory
NODE_OPTIONS=--max-old-space-size=4096
Execution Timeout
Increase timeout
EXECUTIONS_TIMEOUT=7200 EXECUTIONS_TIMEOUT_MAX=14400
Logs
Docker logs
docker logs n8n -f
Increase verbosity
N8N_LOG_LEVEL=debug
Output Format
DEPLOYMENT: Type: [Docker/K8s/NPM] Database: [SQLite/PostgreSQL/MySQL] Mode: [Single/Queue]
ENVIRONMENT: [Key environment variables]
SCALING: Workers: [Number] Concurrency: [Per worker]
SECURITY: Auth: [Method] SSL: [Yes/No] Secrets: [Storage method]
MONITORING: Metrics: [Endpoint] Logs: [Destination] Alerts: [Configuration]