Installation Guide

This guide covers different installation methods for n8n, from local development to production deployments. Choose the method that best fits your infrastructure and requirements.

Requirements:

Node.js 22.16+ (for npm installation)
Docker 20.10+ (for Docker installation)
PostgreSQL 13+ (recommended for production)

Installation Methods

npm

Best for local development and small deployments

Docker

Recommended for production and containerized environments

Kubernetes

Best for large-scale, highly available deployments

npm Installation

Global Installation

Install n8n globally using npm:

Install n8n

npm install n8n -g

Start n8n

n8n

n8n will start and be accessible at http://localhost:5678

Configure (Optional)

Set environment variables for your setup:

export N8N_BASIC_AUTH_ACTIVE=true
export N8N_BASIC_AUTH_USER=admin
export N8N_BASIC_AUTH_PASSWORD=secure_password
n8n

Quick Start (No Installation)

For trying n8n without installation:

npx n8n

Use npx for quick tests and demos. For production, use a proper installation method.

Running Specific Commands

The n8n CLI supports multiple commands:

# Start the main n8n instance
n8n start

# Or simply
n8n

The n8n binary is located at /packages/cli/bin/n8n in the source code. It checks your Node.js version and loads the configuration before starting.

Docker Installation

Basic Docker Setup

Create Data Volume

docker volume create n8n_data

Run n8n Container

docker run -d \
  --name n8n \
  -p 5678:5678 \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

Check Status

docker ps
docker logs n8n

Docker Compose Setup

For production deployments, use Docker Compose:

docker-compose.yml

version: '3.8'

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: n8n_password
      POSTGRES_DB: n8n
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U n8n']
      interval: 5s
      timeout: 5s
      retries: 10

  n8n:
    image: docker.n8n.io/n8nio/n8n
    restart: unless-stopped
    ports:
      - '5678:5678'
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=n8n_password
      - N8N_ENCRYPTION_KEY=your_encryption_key_here
      - N8N_WEBHOOK_URL=https://your-domain.com/
      - N8N_EDITOR_BASE_URL=https://your-domain.com/
      - GENERIC_TIMEZONE=America/New_York
      - N8N_LOG_LEVEL=info
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  postgres_data:
  n8n_data:

Deploy with:

docker-compose up -d

Always set a strong N8N_ENCRYPTION_KEY in production. This key encrypts sensitive data like credentials. If lost, you cannot decrypt existing credentials.

Docker Compose with Queue Mode

For high-volume workflows, use queue mode with separate worker instances:

docker-compose-queue.yml

version: '3.8'

services:
  redis:
    image: redis:7
    restart: unless-stopped
    volumes:
      - redis_data:/data
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 5s
      timeout: 5s
      retries: 10

  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: n8n_password
      POSTGRES_DB: n8n
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U n8n']
      interval: 5s
      timeout: 5s
      retries: 10

  n8n-main:
    image: docker.n8n.io/n8nio/n8n
    restart: unless-stopped
    ports:
      - '5678:5678'
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=n8n_password
      - QUEUE_BULL_REDIS_HOST=redis
      - EXECUTIONS_MODE=queue
      - N8N_ENCRYPTION_KEY=your_encryption_key_here
      - N8N_WEBHOOK_URL=https://your-domain.com/
      - N8N_EDITOR_BASE_URL=https://your-domain.com/
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  n8n-worker:
    image: docker.n8n.io/n8nio/n8n
    restart: unless-stopped
    command: worker
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=n8n_password
      - QUEUE_BULL_REDIS_HOST=redis
      - EXECUTIONS_MODE=queue
      - N8N_ENCRYPTION_KEY=your_encryption_key_here
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    deploy:
      replicas: 2

volumes:
  redis_data:
  postgres_data:
  n8n_data:

Queue mode requires Redis and separates the main instance (UI + triggers) from worker instances (workflow execution). This allows horizontal scaling of workers.

Configuration

Essential Environment Variables

n8n is highly configurable through environment variables:

Database Configuration

# SQLite is used by default
DB_TYPE=sqlite

# Optional: Run VACUUM on startup
DB_SQLITE_VACUUM_ON_STARTUP=true

SQLite is not recommended for production use. Use PostgreSQL for better performance and reliability.

Security Configuration

# Encryption key for credentials (REQUIRED for production)
N8N_ENCRYPTION_KEY=your_very_long_random_encryption_key

# JWT secret for authentication
N8N_JWT_SECRET=your_jwt_secret

# Basic auth (if not using user management)
N8N_BASIC_AUTH_ACTIVE=true
N8N_BASIC_AUTH_USER=admin
N8N_BASIC_AUTH_PASSWORD=secure_password

Webhook & URL Configuration

# Public URL for webhooks
N8N_WEBHOOK_URL=https://your-domain.com/

# Editor/UI base URL
N8N_EDITOR_BASE_URL=https://your-domain.com/

# Path prefix (if behind reverse proxy)
N8N_PATH=/n8n/

Execution Configuration

# Execution mode: regular or queue
EXECUTIONS_MODE=regular

# Queue mode settings (if using queue)
QUEUE_BULL_REDIS_HOST=localhost
QUEUE_BULL_REDIS_PORT=6379
QUEUE_BULL_REDIS_PASSWORD=redis_password

# Maximum concurrent executions
N8N_CONCURRENCY_PRODUCTION_LIMIT=10

Logging & Monitoring

# Log level: error, warn, info, debug, verbose
N8N_LOG_LEVEL=info

# Log output: console, file
N8N_LOG_OUTPUT=console

# Timezone
GENERIC_TIMEZONE=America/New_York

For a complete list of configuration options, see the n8n documentation or check /packages/cli/src/config/ in the source code.

Configuration File

Alternatively, use a configuration file:

config/default.json

{
  "database": {
    "type": "postgresdb",
    "postgresdb": {
      "host": "localhost",
      "port": 5432,
      "database": "n8n",
      "user": "n8n",
      "password": "secure_password"
    }
  },
  "credentials": {
    "overwrite": {
      "data": "{}"
    }
  },
  "executions": {
    "mode": "regular",
    "timeout": 3600,
    "maxTimeout": 3600
  },
  "timezone": "America/New_York"
}

Place this file in the ~/.n8n/config/ directory or set NODE_CONFIG_DIR environment variable.

Production Deployment

Reverse Proxy Setup (nginx)

For production, put n8n behind a reverse proxy:

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/ssl/certs/your-domain.crt;
    ssl_certificate_key /etc/ssl/private/your-domain.key;

    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_cache_bypass $http_upgrade;
        
        # Required for webhooks
        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;
        
        # Increase timeouts for long-running workflows
        proxy_connect_timeout 3600;
        proxy_send_timeout 3600;
        proxy_read_timeout 3600;
        send_timeout 3600;
    }
}

Systemd Service

Create a systemd service for n8n:

/etc/systemd/system/n8n.service

[Unit]
Description=n8n - Workflow Automation Tool
After=network.target

[Service]
Type=simple
User=n8n
WorkingDirectory=/home/n8n
Environment="NODE_ENV=production"
Environment="N8N_ENCRYPTION_KEY=your_encryption_key"
Environment="DB_TYPE=postgresdb"
Environment="DB_POSTGRESDB_HOST=localhost"
Environment="DB_POSTGRESDB_DATABASE=n8n"
Environment="DB_POSTGRESDB_USER=n8n"
Environment="DB_POSTGRESDB_PASSWORD=secure_password"
Environment="N8N_WEBHOOK_URL=https://your-domain.com/"
Environment="N8N_EDITOR_BASE_URL=https://your-domain.com/"
ExecStart=/usr/local/bin/n8n start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable n8n
sudo systemctl start n8n
sudo systemctl status n8n

Building from Source

For development or custom builds:

Clone Repository

git clone https://github.com/n8n-io/n8n.git
cd n8n

Install Dependencies

# Requires pnpm 10.22.0+
npm install -g pnpm
pnpm install

Build All Packages

pnpm build > build.log 2>&1

Build output is redirected to avoid overwhelming the console. Check build.log for any errors.

Start Development

# Start all services in dev mode
pnpm dev

# Or start only backend
pnpm dev:be

# Or start only frontend
pnpm dev:fe

n8n uses a monorepo structure with pnpm workspaces. Always use pnpm instead of npm or yarn.

Advanced Configuration

Multi-Main Setup (High Availability)

For enterprise deployments, enable multi-main mode:

# Enable multi-main setup (requires Enterprise license)
EXECUTIONS_MODE=queue
N8N_MULTI_MAIN_SETUP_ENABLED=true
QUEUE_BULL_REDIS_HOST=redis_host

Multi-main setup requires:

Queue mode (Redis)
Enterprise license
PostgreSQL database
Multiple n8n main instances

External Secrets

Load sensitive values from external sources:

# Use environment variables for secrets
export N8N_ENCRYPTION_KEY=$(cat /run/secrets/encryption_key)
export DB_POSTGRESDB_PASSWORD=$(cat /run/secrets/db_password)

Custom Node Loading

Load custom nodes from a directory:

N8N_CUSTOM_EXTENSIONS=/path/to/custom/nodes

Upgrading n8n

npm Upgrade

npm install n8n@latest -g

Docker Upgrade

# Pull latest image
docker pull docker.n8n.io/n8nio/n8n:latest

# Restart container
docker-compose down
docker-compose up -d

Always backup your database before upgrading. n8n runs database migrations automatically on startup.

Backup & Recovery

Backup Database

# Backup
pg_dump -U n8n n8n > n8n_backup_$(date +%Y%m%d).sql

# Restore
psql -U n8n n8n < n8n_backup_20260219.sql

Backup n8n Data Directory

tar -czf n8n_data_backup_$(date +%Y%m%d).tar.gz ~/.n8n/

Monitoring & Health Checks

Health Check Endpoint

n8n exposes a health check endpoint:

curl http://localhost:5678/healthz

Metrics (Prometheus)

Enable Prometheus metrics:

N8N_METRICS=true
N8N_METRICS_PORT=9090

Metrics are available at:

http://localhost:9090/metrics

Troubleshooting

Database Connection Issues

Check Database

# PostgreSQL
psql -U n8n -h localhost -d n8n

# Check connection
\conninfo

Verify Configuration

Check environment variables are set correctly:

echo $DB_TYPE
echo $DB_POSTGRESDB_HOST

Check Logs

# Docker
docker logs n8n

# Systemd
journalctl -u n8n -f

Performance Issues

Use PostgreSQL instead of SQLite
Enable queue mode for high-volume workflows
Increase worker instances
Configure execution timeouts appropriately
Enable database connection pooling

Permission Errors

# Fix n8n data directory permissions
sudo chown -R $USER:$USER ~/.n8n/
chmod 700 ~/.n8n/

Getting Help

Community Forum

Get installation support from the community

Documentation

Detailed configuration documentation

GitHub Issues

Report installation bugs

Enterprise Support

Contact for enterprise installation support

Getting Started

Self-Hosting

Building Workflows

AI Workflows

Node Development

CLI Reference

​Installation Guide

​Installation Methods

npm

Docker

Kubernetes

​npm Installation

​Global Installation

​Quick Start (No Installation)

​Running Specific Commands

​Docker Installation

​Basic Docker Setup

​Docker Compose Setup

​Docker Compose with Queue Mode

​Configuration

​Essential Environment Variables

​Database Configuration

​Security Configuration

​Webhook & URL Configuration

​Execution Configuration

​Logging & Monitoring

​Configuration File

​Production Deployment

​Reverse Proxy Setup (nginx)

​Systemd Service

​Building from Source

​Advanced Configuration

​Multi-Main Setup (High Availability)

​External Secrets

​Custom Node Loading

​Upgrading n8n

​npm Upgrade

​Docker Upgrade

​Backup & Recovery

​Backup Database

​Backup n8n Data Directory

​Monitoring & Health Checks

​Health Check Endpoint

​Metrics (Prometheus)

​Troubleshooting

​Database Connection Issues

​Performance Issues

​Permission Errors

​Getting Help

Community Forum

Documentation

GitHub Issues

Enterprise Support

Installation Guide

Installation Methods

npm Installation

Global Installation

Quick Start (No Installation)

Running Specific Commands

Docker Installation

Basic Docker Setup

Docker Compose Setup

Docker Compose with Queue Mode

Configuration

Essential Environment Variables

Database Configuration

Security Configuration

Webhook & URL Configuration

Execution Configuration

Logging & Monitoring

Configuration File

Production Deployment

Reverse Proxy Setup (nginx)

Systemd Service

Building from Source

Advanced Configuration

Multi-Main Setup (High Availability)

External Secrets

Custom Node Loading

Upgrading n8n

npm Upgrade

Docker Upgrade

Backup & Recovery

Backup Database

Backup n8n Data Directory

Monitoring & Health Checks

Health Check Endpoint

Metrics (Prometheus)

Troubleshooting

Database Connection Issues

Performance Issues

Permission Errors

Getting Help