N8n Self Host

n8n Self-Host

Install and operate self-hosted n8n responsibly. Most "n8n is broken in production" tickets come from skipped Day-0 setup: wrong WEBHOOK_URL, missing N8N_ENCRYPTION_KEY, default SQLite under load, no backup.

References: DOCKER.md | ENV_VARS.md | QUEUE_MODE.md | REVERSE_PROXY.md | SECURITY.md | BACKUP_UPGRADE.md

Lessons: LESSONS_LEARNED.md — read before non-trivial work.

Authoritative docs: https://docs.n8n.io/hosting/

Day-0 checklist (DO NOT SKIP)

Before activating any production workflow, these are non-negotiable:

1. Set N8N_ENCRYPTION_KEY to a random 32+ character string. Without it, n8n generates one on first boot and writes it to disk — if that file is lost, ALL credentials become unrecoverable.

   openssl rand -hex 32
   

2. Set WEBHOOK_URL to the public URL where users reach the instance. n8n reports webhook URLs based on this env. If it doesn't match what callers hit, webhooks 404.

3. Set GENERIC_TIMEZONE to your team's timezone (e.g. America/New_York). Schedule Trigger uses this as the default.

4. Use Postgres, not SQLite. SQLite is the default but doesn't survive concurrent writes. Migrate before any real load.

5. Set up a reverse proxy with HTTPS. n8n serves plaintext by default. Put nginx/Traefik/Caddy in front and terminate TLS. See REVERSE_PROXY.md.

6. Plan backups. At minimum: the Postgres database (or SQLite file) + /home/node/.n8n config dir + binary data directory (if filesystem mode). See BACKUP_UPGRADE.md.

7. Decide deployment mode early. If you'll need to scale beyond ~50 concurrent executions or have long-running workflows, plan for queue mode from the start. See QUEUE_MODE.md.

Minimum viable Docker setup (single instance)

# docker-compose.yml
services:
  n8n:
    image: n8nio/n8n:latest
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      # Identity / encryption — DO NOT change after first boot
      N8N_ENCRYPTION_KEY: "${N8N_ENCRYPTION_KEY}"

      # Public URL
      N8N_HOST: n8n.example.com
      N8N_PROTOCOL: https
      WEBHOOK_URL: https://n8n.example.com/

      # Timezone
      GENERIC_TIMEZONE: America/New_York
      TZ: America/New_York

      # DB — Postgres
      DB_TYPE: postgresdb
      DB_POSTGRESDB_HOST: postgres
      DB_POSTGRESDB_PORT: 5432
      DB_POSTGRESDB_DATABASE: n8n
      DB_POSTGRESDB_USER: n8n
      DB_POSTGRESDB_PASSWORD: "${POSTGRES_PASSWORD}"

      # Reasonable defaults
      EXECUTIONS_DATA_PRUNE: "true"
      EXECUTIONS_DATA_MAX_AGE: "336"    # 14 days in hours
      N8N_METRICS: "true"
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      - postgres

  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
      POSTGRES_DB: n8n
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  n8n_data:
  postgres_data:

# .env
N8N_ENCRYPTION_KEY=<openssl rand -hex 32 output>
POSTGRES_PASSWORD=<a long random password>

docker compose up -d

Then put nginx/Traefik/Caddy in front to terminate TLS for n8n.example.com. See REVERSE_PROXY.md.

Queue mode — when and how

Switch to queue mode when ANY of these are true:

• More than ~50 concurrent active executions expected.
• Workflows that take >5 minutes (so the main process isn't tied up).
• Need to scale horizontally across machines.
• Need rolling restarts of workers without downtime.

Queue mode separates the main process (UI, webhooks, scheduler) from worker processes (actual workflow execution), using Redis as a queue.

                 ┌──────────────┐
   Browser ─────▶│   n8n main   │──┐
   Webhook ─────▶│  (UI/API)    │  │ enqueue
                 └──────────────┘  │
                                   ▼
                              ┌────────┐
                              │ Redis  │
                              └────────┘
                                   ▲
                                   │ dequeue
                 ┌─────────────────┴────────────────┐
                 │                                  │
         ┌──────────────┐                  ┌──────────────┐
         │  n8n worker  │   ...            │  n8n worker  │
         └──────────────┘                  └──────────────┘

See QUEUE_MODE.md for the full Compose file and tuning.

Critical env vars (always set in production)

See ENV_VARS.md for the full catalog.

What breaks in production (most common)

Procedure (any self-host request)

1. Identify what the user actually needs. "Install n8n" can mean anything from docker run to a multi-node HA cluster. Ask:

   • Cloud provider / on-prem?
   • Expected concurrent executions and workflow duration?
   • HTTPS termination already handled?
   • Existing Postgres / Redis available?
   • SSO required? (Enterprise)

2. Walk through Day-0 checklist before any specific setup. If the user says "just give me Docker Compose", give them the Minimum viable Docker setup above and DO call out the checklist items they should set.

3. Use real values, not placeholders. When generating env vars, run openssl rand -hex 32 and put the actual output in the user's .env. Don't leave <YOUR_KEY_HERE> for them to forget about.

4. Generate a single docker-compose.yml + .env + reverse-proxy snippet as a copy-paste-ready bundle. Don't make the user assemble pieces.

5. For upgrades, ALWAYS back up first. See BACKUP_UPGRADE.md. Do not run docker compose pull && docker compose up -d without confirmation if the user is on a major version boundary.

6. Update LESSONS_LEARNED.md if you discovered a new hosting gotcha.

Best practices

Do:

• Pin the n8n image version (n8nio/n8n:1.78.0) in production, not latest.
• Run as the non-root node user (the official image already does).
• Mount /home/node/.n8n as a named Docker volume or persistent disk — this contains the SQLite DB (if using SQLite), the auto-generated encryption key fallback, and some local config.
• Keep N8N_ENCRYPTION_KEY in a secrets manager. Treat losing it as equivalent to losing all credentials.
• Monitor /healthz/readiness and /healthz for health checks.
• Scrape /metrics with Prometheus for execution counts, durations, queue depth.
• Run periodic EXECUTIONS_DATA_PRUNE audits — if disk grows despite pruning enabled, check EXECUTIONS_DATA_MAX_AGE setting.
• For Kubernetes, use the official Helm chart: https://github.com/n8n-io/n8n-hosting/tree/main/kubernetes.

Don't:

• Don't run multiple n8n main processes against the same Postgres without queue mode. Schedules will fire multiple times, webhooks may double-process.
• Don't use SQLite in production. Period.
• Don't expose port 5678 directly to the internet — always behind a proxy with TLS.
• Don't rotate N8N_ENCRYPTION_KEY casually — it requires re-encrypting all stored credentials (n8n provides a CLI for this; do it deliberately).
• Don't skip backups because "Postgres has its own backup". You also need /home/node/.n8n (config, license file, custom nodes if installed there) and the binary data directory.

Continuous learning

Self-hosting touches a lot of moving parts (Docker, Postgres, Redis, reverse proxy, your environment's specifics). Every non-trivial deployment discovers something worth capturing. After any setup, debugging session, or upgrade, append a dated entry to LESSONS_LEARNED.md.