n8n Deployment & Usage Guide

1. Prerequisites

Minimum Requirements

• Node.js: 18.x LTS or later (required for npx/source installation)
• npm: 9.x or later (included with Node.js)
• Docker: 20.10+ (recommended for production deployment)
• Git: 2.35+ (for source installation)
• Memory: 2GB RAM minimum (4GB+ recommended for production)
• Storage: 1GB free space (additional space required for execution data)

Optional Dependencies

• PostgreSQL: 13+ (for production database instead of default SQLite)
• Redis: 6.2+ (for queue mode and multi-instance setups)
• Reverse Proxy: Nginx, Traefik, or Caddy (for SSL termination)

2. Installation

Choose one of the following methods based on your use case:

Option A: Quick Start (npx)

Fastest way to run n8n without installation:

npx n8n

Access the editor at http://localhost:5678

Option B: Docker (Recommended for Production)

# Create persistent volume
docker volume create n8n_data

# Run n8n container
docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

Option C: Source Installation (Development)

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

# Install dependencies (n8n uses pnpm)
npm install -g pnpm
pnpm install

# Build packages
pnpm build

# Start development server
pnpm start

3. Configuration

Environment Variables

Create a .env file or export variables before starting:

Basic Authentication Setup

export N8N_BASIC_AUTH_ACTIVE=true
export N8N_BASIC_AUTH_USER=admin
export N8N_BASIC_AUTH_PASSWORD=secure_password_here

Database Configuration (PostgreSQL)

export DB_TYPE=postgresdb
export DB_POSTGRESDB_HOST=localhost
export DB_POSTGRESDB_PORT=5432
export DB_POSTGRESDB_DATABASE=n8n
export DB_POSTGRESDB_USER=n8n_user
export DB_POSTGRESDB_PASSWORD=secure_db_password

4. Build & Run

Development Mode

# Watch mode for automatic rebuilding
pnpm dev

# Or start specific package
cd packages/cli
pnpm start

Production Build

# Clean build
pnpm clean
pnpm build

# Start production server
cd packages/cli
pnpm start

Docker with Custom Environment

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -e N8N_BASIC_AUTH_ACTIVE=true \
  -e N8N_BASIC_AUTH_USER=admin \
  -e N8N_BASIC_AUTH_PASSWORD=changeme \
  -e WEBHOOK_URL=https://n8n.yourdomain.com/ \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

5. Deployment

Docker Compose (Production Ready)

Create docker-compose.yml:

version: '3.8'

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    restart: always
    ports:
      - "5678:5678"
    environment:
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=secure_password
      - WEBHOOK_URL=https://n8n.yourdomain.com/
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=postgres_password
    volumes:
      - n8n_data:/home/node/.n8n

  postgres:
    image: postgres:15-alpine
    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:

Deploy:

docker-compose up -d

Kubernetes (Helm)

# Add n8n Helm repository
helm repo add n8n https://n8n-io.github.io/n8n-helm-chart
helm repo update

# Install with custom values
helm install n8n n8n/n8n \
  --set service.type=LoadBalancer \
  --set persistence.enabled=true \
  --set persistence.size=10Gi

Cloud Platforms

AWS (ECS/Fargate):

• Use official Docker image
• Configure RDS PostgreSQL for persistence
• Set up Application Load Balancer with SSL

DigitalOcean App Platform:

• Use Dockerfile deployment
• Add managed PostgreSQL database
• Configure environment variables in dashboard

Railway/Render:

• Connect GitHub repository
• Add PostgreSQL service
• Set WEBHOOK_URL to deployed domain

6. Troubleshooting

Permission Denied on Volume (Docker)

Issue: EACCES: permission denied, mkdir '/home/node/.n8n' Solution: Run with user ID 1000 (node user):

docker run -it --rm \
  --user 1000:1000 \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

Port Already in Use

Issue: Error: listen EADDRINUSE: address already in use :::5678 Solution: Change host port mapping:

docker run -p 5679:5678 docker.n8n.io/n8nio/n8n

Out of Memory (Build)

Issue: JavaScript heap out of memory during build Solution: Increase Node memory limit:

export NODE_OPTIONS="--max-old-space-size=4096"
pnpm build

Workflows Not Executing

Issue: Executions stuck in "Running" state Solution:

• Check EXECUTIONS_MODE is set correctly
• Verify Redis connection if using queue mode
• Check logs: docker logs n8n

Database Connection Failed

Issue: Connection refused to PostgreSQL Solution:

• Verify PostgreSQL is running and accessible
• Check firewall rules
• Ensure database exists: createdb n8n

Webhooks Not Receiving Data

Issue: 404 errors on webhook URLs Solution:

• Verify WEBHOOK_URL environment variable matches your public URL
• For testing locally: use WEBHOOK_URL=http://localhost:5678/
• Ensure reverse proxy forwards headers correctly

Getting Help

• Documentation: https://docs.n8n.io
• Community Forum: https://community.n8n.io
• GitHub Issues: https://github.com/n8n-io/n8n/issues