Isometric 3D illustration of a self-hosted n8n stack: an n8n cube on a Docker container with a PostgreSQL database and a padlock connected to the same platform

Self-Host n8n on Ubuntu with Docker: Complete Setup 2026

ByThe Nguyen

This guide is different. It is the definitive roadmap for deploying a bulletproof, production-grade n8n instance on Ubuntu using Docker Compose. We’ll take you step-by-step from a fresh server to a fully secured and persistent automation engine.For a managed deployment option, consider using Coolify as your self-hosted PaaS.

You will get a complete, copy-and-paste configuration blueprint, learn how to secure your instance with automatic SSL, manage data correctly to prevent data loss, and build a system you can rely on for business-critical workflows like keyword research automation. This is the blueprint for doing it right, once.

This guide cuts through the noise, and it will walk you through:

  • ✅ Installing n8n on an Ubuntu server with Docker Compose, Traefik, and PostgreSQL
  • ✅ Safely upgrading n8n to a pinned or latest version
  • ✅ Backing up and restoring your entire stack to prevent data loss
  • ✅ Adding monitoring with Prometheus & Grafana for dashboards and alerts

By the end, you’ll fully understand the lifecycle of a production-ready n8n instance,and you’ll be able to install, upgrade, back up, and restore your own deployment without depending on any other platform. For more, see our guide on our n8n monitoring guide.

Prefer automation?

Prefer not to hand-configure? n8n Manager gives you a turnkey, production-ready setup in minutes. One script covers install, repeatable envs, upgrades, and full disaster recovery (backup & restore). Enable monitoring to auto-provision Prometheus + Grafana and get real-time dashboards and alerts on your n8n’s health and performance.

What Are the Core Principles of a Production n8n Setup?

Before we touch the command line, let’s establish three non-negotiable principles. Ignoring these is the root cause of nearly all self-hosting failures. Our entire setup is built on this foundation.

  • Principle 1: Use a Production Database. The default SQLite database is a time bomb for any serious use case. It can’t handle simultaneous workflow executions and is prone to data corruption. We will use PostgreSQL, a battle-tested database that ensures data integrity and scalability from day one.
  • Principle 2: Never Expose n8n Directly. Running n8n and exposing its port to the internet is a massive security risk. We will use Traefik as a reverse proxy. It acts as a secure gatekeeper, handling automatic SSL/TLS encryption (the green padlock), managing traffic, and protecting your n8n application.
  • Principle 3: Guarantee Data Persistence. By default, Docker containers are ephemeral. If you remove the container, your data is gone. We will use named volumes to ensure all your workflows, credentials, and database information are stored safely and persist through updates and restarts.

Prerequisites

To follow this guide, you will need:

  • A fresh Ubuntu Server (22.04 or newer is recommended). A cloud provider like DigitalOcean, Vultr, or Hetzner is a great choice.
  • A registered domain name (e.g., n8n.yourcompany.com) with the DNS A record pointed to your server’s public IP address.
  • Basic familiarity with the command line.
  • An SSH client to connect to your server.

How much VPS do you need?

Sizing is the thing people get wrong most often, and they get it wrong in one direction: pushing worker concurrency higher instead of adding a worker. These are the numbers the toolkit ships with.

VPS (vCPU / RAM)Suggestion
1 vCPU / 2 GB1 worker at concurrency 3-5
2 vCPU / 4 GB1-2 workers at concurrency 5
4 vCPU / 8 GB2 workers at concurrency 8
8+ vCPU / 16+ GB3-4 workers at concurrency 8-10

Concurrency is not free throughput. A worker waiting on a slow downstream API looks idle while it still holds every slot, so raising the number makes the queue back up rather than drain. Add a worker before you raise concurrency.

What Do You Need to Run n8n (and Why)?

The Production Stack (at a glance):

  • Docker + Docker Compose (on Ubuntu): Orchestrates n8n, PostgreSQL, and Traefik into one repeatable, production-ready setup.
  • PostgreSQL: Stores workflows, credentials, executions, and logs reliably.
  • Traefik (reverse proxy): Handles HTTPS termination, domain routing, and Let’s Encrypt certificates automatically.
  • n8n application: The automation engine you’ll access from your browser.
n8n deployment ubuntu vps
 Self-hosting n8n with Docker Compose, Traefik and PostgreSQL

n8n Single Mode Observability Architecture:

n8n single mode architecture with Docker Compose, Traefik, PostgreSQL, and observability
 Self-hosting n8n with Docker Compose, Traefik and PostgreSQL and Observability

Why Docker Compose on Ubuntu?

The best practice for production is to run n8n using Docker Compose, because it:

  • Starts/stops the entire stack with one command.
  • Runs each service in its own container for safety and easier debugging.
  • Simplifies upgrades and rollbacks.
  • Provides resilience with restart policies and persistent volumes.
  • Centralizes environment variables, storage, and scaling in one file.

Why PostgreSQL (not SQLite)?

Use PostgreSQL in production instead of SQLite because it:

  • Handles multiple workers and higher throughput.
  • Supports queue mode and scaling.
  • Enables safer backups and migrations.
  • Maintains stronger data integrity under load.

If you are considering a self-hosted PaaS for deploying n8n and other services, our Coolify vs Dokploy comparison covers which platform works best for different use cases, including n8n deployment.

Why Traefik (not Nginx or Caddy)?

For HTTPS and routing, Traefik is the best choice for Dockerized n8n because it:

  • Auto-discovers containers with Docker labels.
  • Manages Let’s Encrypt SSL certificates automatically.
  • Supports sticky sessions and load balancing.
  • Integrates smoothly with Docker Compose.

How Do You Automate n8n Management with Shell Scripts?

Managing n8n by hand (installing, upgrading, backing up, restoring) takes time and invites mistakes. That’s why I built n8n_manager.sh, a script that automates the entire lifecycle of a self-hosted n8n instance in just a few commands.

Everything in this section is written against n8n-toolkit v3.4.0, which pins n8n 2.17.7 in its .env.example. The command reference below is generated from ./n8n_manager.sh --help, and tests/unit/test_docs_align.bats fails the build whenever the documented CLI and the real one drift apart. If a flag appears here, the script accepts it.

If you want to try it before pointing DNS at anything, --local installs on *.localhost with a self-signed certificate and skips the public DNS check and Let’s Encrypt entirely. It ships as a Compose overlay, so the production docker-compose.yml is byte-identical whether or not you use it, and later commands detect local mode from the overlay rather than a flag you have to remember. Requires Docker Compose 2.24+, and it is for evaluation or CI, not for a public server.

What it covers:

  • Install, Deploy n8n with Docker Compose, PostgreSQL, and Traefik (HTTPS via Let’s Encrypt).
  • Upgrade, Safely pull a pinned or latest n8n image and redeploy with validation and logs.
  • Backup, Archive DB dumps, named volumes, SSL certs, and config files (checksums included).
  • Restore, Recover from a local file or rclone remote in minutes.
  • Monitoring, One-flag setup for Prometheus + Grafana with pre-provisioned dashboards and alert rules.

Quick Start

Download the script:

# You can set up this project in two ways, depending on your experience:

# Option 1, Developers (Git)
git clone https://github.com/thenguyenvn90/n8n-toolkit.git
cd n8n-toolkit

# Option 2, Download as ZIP
sudo apt update && sudo apt install -y unzip
curl -L -o n8n-toolkit.zip https://github.com/thenguyenvn90/n8n-toolkit/archive/refs/heads/main.zip
unzip n8n-toolkit.zip

#After unzipping, GitHub appends -main to the folder name.
cd n8n-toolkit-main

The n8n_manager.sh script is the main tool to install, upgrade, backup, restore, cleanup and monitor your n8n stack. Check detail here n8n Manager, User Guide

Usage: ./n8n_manager.sh [ONE ACTION] [OPTIONS]

Actions (choose exactly one):
  -a, --available
        List available n8n versions

  -i, --install <DOMAIN>
        Install n8n with the given base domain (e.g., example.com)
        Optional: --mode single|queue  (default: single)
        Optional: -v|--version <tag>

  -u, --upgrade
        Upgrade n8n to target version (or latest). Domain/FQDNs are read from .env.

  -b, --backup
        Run backup (skip if no changes unless -f)

  -r, --restore <FILE_OR_REMOTE>
        Restore from local file or rclone remote (e.g. gdrive:folder/file.tar.gz)

  -c, --cleanup [safe|all]  Stop stack & remove resources (preview; confirm in 'all')

Options:
  --mode <single|queue>     (install only; default: single)
  -v, --version <tag>       Target n8n version (default: latest stable)
  -m, --ssl-email <email>   LE certificate email (install/upgrade)
  -d, --dir <path>          Target n8n directory (default: /home/n8n)
  -l, --log-level <LEVEL>   DEBUG | INFO (default) | WARN | ERROR
  -f, --force               Upgrade: allow downgrade or redeploy; Backup: force even if unchanged
  -e, --email-to <email>    Send notifications to this address (requires SMTP_USER/SMTP_PASS env)
  -n, --notify-on-success   Also email on success (not just failures)
  -s, --remote-name <name>  rclone remote root (e.g. gdrive-user or gdrive-user:/n8n-backups)
  -h, --help                Show this help

# Monitoring-related (install-time):
  --monitoring                        Enable Prometheus/Grafana profile
  --expose-prometheus                 Expose Prometheus publicly (default: private)
  --subdomain-n8n <sub>               Override n8n subdomain (default: n8n)
  --subdomain-grafana <sub>           Override Grafana subdomain (default: grafana)
  --subdomain-prometheus <sub>        Override Prometheus subdomain (default: prometheus)
  --basic-auth-user <user>            Traefik basic auth user for Grafana/Prometheus
  --basic-auth-pass <pass>            Traefik basic auth pass for Grafana/Prometheus

Examples:
  ./n8n_manager.sh -a
      # List available versions

  ./n8n_manager.sh --install example.com -m [email protected]
      # Install the latest n8n version with single mode

  ./n8n_manager.sh --install example.com -m [email protected] -v 1.105.3 --mode queue
      # Install a specific n8n version with queue mode

  ./n8n_manager.sh --install example.com -m [email protected] -d /path/to/n8n --mode queue
      # Install the latest n8n version (queue mode) to a specific target directory

  ./n8n_manager.sh --install example.com -m [email protected] --mode queue --monitoring --basic-auth-user admin --basic-auth-pass 'StrongPass123'
      # Install the latest n8n version (queue mode) with monitoring (Grafana + Prometheus)

  ./n8n_manager.sh --upgrade
      # Upgrade to the latest n8n version (domain/FQDNs read from .env)

  ./n8n_manager.sh --upgrade -f -v 1.107.2
      # Upgrade to a specific n8n version

  ./n8n_manager.sh --backup --remote-name gdrive-user --email-to [email protected] --notify-on-success
      # Backup and upload to Google Drive, notify via email

  ./n8n_manager.sh --restore backups/your_backup_file.tar.gz
      # Restore with the tar.gz file at local

Example: install n8n (single mode) in Ubuntu VPS with docker compose

n8n single mode deployment

If you want to enable the monitoring option, follow my detailed guide here: install n8n single mode with monitoring

Step-by-Step Manual Install n8n Single Mode on Ubuntu with Docker

In this section, we’ll manually set up a production-ready n8n stack on Ubuntu using Docker Compose. The stack will include:

  • n8n, the automation platform
  • PostgreSQL, database for storing workflows and credentials
  • Traefik, reverse proxy for HTTPS and domain routing
  • Let’s Encrypt, automatic SSL certificate management

Step 1: Prepare VPS and Update DNS record

Use this as a starting point. Size up or down after you observe real traffic, execution duration, and resource headroom.

Use casevCPURAMDisk (SSD)Notes
Dev / trial12 GB25, 40 GBFine for tests and a few light workflows. Expect slowdowns under load.
Small production24 GB40, 60 GBDozens of workflows, low concurrency, webhooks OK. Solid default for new installs.
Growing production48 GB80, 100 GBMany workflows, frequent webhooks, large binaries. At this stage, consider Queue Mode for throughput & isolation.

To make your n8n instance accessible online, create a dedicated subdomain that points to your server’s IP address.

Add the following DNS record in your domain provider’s DNS settings:

Record TypeName (Subdomain)Value (Destination)
An8n (or your chosen subdomain)<your_server_IP_address>

Wait a few minutes for DNS propagation, then verify that your domain resolves to your VPS IP.

DOMAIN="n8n.yourdomain.com"; SERVER_IP="$(curl -s https://api.ipify.org)"; \
DNS_IPS="$( (command -v dig >/dev/null && dig +short A "$DOMAIN") || getent ahostsv4 "$DOMAIN" | awk '{print $1}' )"; \
echo "Server IP: $SERVER_IP"; echo "DNS A records for $DOMAIN:"; echo "$DNS_IPS"; \
echo "$DNS_IPS" | grep -Fxq "$SERVER_IP" && echo "✅ PASS: $DOMAIN points to this server" || echo "❌ FAIL: $DOMAIN does not point to this server"

Step 2: Install Docker and Docker Compose

Docker lets us run n8n, PostgreSQL, and Traefik in isolated containers. Docker Compose ties them together into a single stack.

# Step 1: Install required dependencies
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release

# Step 2: Add Docker’s official GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Step 3: Add the Docker repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Step 4: Install Docker Engine and Compose v2
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Step 5: Allow user to run Docker without sudo
sudo usermod -aG docker ${USER}
# Register the `docker` group membership with current session without changing your primary group
exec sg docker newgrp

Step 3: Create docker-compose.yml and .env file

Prepare the project directory

It’s best to install n8n in a dedicated folder on your VPS. This keeps everything in one place, so upgrade, backups, restore are easy to manage later.

mkdir -p /home/n8n

Create docker-compose.yml

You can copy the docker-compose.yml here or from my GitHub: single-mode/docker-compose.yml

Example docker-compose.yml 
services:
  traefik:
    image: traefik:v2.11
    restart: unless-stopped
    command:
      - "--api.dashboard=false"
      # EntryPoints
      - "--entrypoints.web.address=:80"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--entrypoints.websecure.address=:443"
      # Providers
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--providers.docker.network=n8n-network"
      # ACME (production)
      - "--certificatesresolvers.le.acme.email=${SSL_EMAIL}"
      - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
      - "--certificatesresolvers.le.acme.tlschallenge=true"
      # Logs
      - "--log.level=INFO"
      - "--accesslog=true"
      # Health check
      - "--ping=true"
      - "--ping.entrypoint=traefikping"
      - "--entrypoints.traefikping.address=:8082"
      # Prometheus metrics
      - "--metrics.prometheus=true"
      - "--metrics.prometheus.addEntryPointsLabels=true"
      - "--metrics.prometheus.addRoutersLabels=true"
      - "--metrics.prometheus.addServicesLabels=true"
      - "--entrypoints.metrics.address=:8081"
      - "--metrics.prometheus.entryPoint=metrics"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - letsencrypt:/letsencrypt
      - ./secrets/htpasswd:/etc/traefik/htpasswd:ro
    networks: [n8n-network]
    security_opt: [no-new-privileges:true]
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:8082/ping"]
      interval: 10s
      timeout: 5s
      start_period: 20s
      retries: 5

  postgres:
    image: postgres:14
    restart: unless-stopped
    env_file: [.env]
    environment:
      - TZ=${GENERIC_TIMEZONE}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks: [n8n-network]
    security_opt: [no-new-privileges:true]
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      start_period: 20s
      retries: 5

  # n8n (single mode)
  main:
    image: docker.n8n.io/n8nio/n8n:${N8N_IMAGE_TAG:-latest}
    restart: unless-stopped
    env_file: [.env]
    environment:
      - TZ=${GENERIC_TIMEZONE}
      - N8N_METRICS=true
    volumes:
      - n8n-data:/home/node/.n8n
      - ./local-files:/files
    depends_on:
      postgres:
        condition: service_healthy
    networks: [n8n-network]
    security_opt: [no-new-privileges:true]
    healthcheck:
      test: ["CMD-SHELL", "wget --spider -q http://localhost:${N8N_PORT:-5678}/healthz || exit 1"]
      interval: 10s
      timeout: 5s
      start_period: 20s
      retries: 5
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=n8n-network"
      # Router & TLS
      - "traefik.http.routers.n8n.rule=Host(`${N8N_FQDN}`)"
      - "traefik.http.routers.n8n.entrypoints=websecure"
      - "traefik.http.routers.n8n.tls=true"
      - "traefik.http.routers.n8n.tls.certresolver=le"
      # Bind the router to the named Traefik service defined below
      - "traefik.http.routers.n8n.service=n8n"
      - "traefik.http.services.n8n.loadbalancer.server.port=${N8N_PORT:-5678}"
      # Middlewares
      - "traefik.http.routers.n8n.middlewares=n8n-headers,n8n-rate,n8n-retry,n8n-compress"
      # Security headers
      - "traefik.http.middlewares.n8n-headers.headers.stsSeconds=315360000"
      - "traefik.http.middlewares.n8n-headers.headers.browserXssFilter=true"
      - "traefik.http.middlewares.n8n-headers.headers.contentTypeNosniff=true"
      - "traefik.http.middlewares.n8n-headers.headers.forceSTSHeader=true"
      - "traefik.http.middlewares.n8n-headers.headers.stsIncludeSubdomains=true"
      - "traefik.http.middlewares.n8n-headers.headers.stsPreload=true"
      # Rate limiting
      - "traefik.http.middlewares.n8n-rate.ratelimit.average=100"
      - "traefik.http.middlewares.n8n-rate.ratelimit.burst=50"
      - "traefik.http.middlewares.n8n-rate.ratelimit.period=1s"
      # Retry & compression
      - "traefik.http.middlewares.n8n-retry.retry.attempts=3"
      - "traefik.http.middlewares.n8n-compress.compress=true"

  # ===== Monitoring (enabled by COMPOSE_PROFILES=monitoring) =====
  prometheus:
    profiles: ["monitoring"]
    image: prom/prometheus:latest
    restart: unless-stopped
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
      - "--storage.tsdb.retention.time=15d"
    volumes:
      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus-data:/prometheus
    networks: [n8n-network]
    security_opt: [no-new-privileges:true]
    labels:
      - "traefik.enable=${EXPOSE_PROMETHEUS:-false}"
      - "traefik.docker.network=n8n-network"
      - "traefik.http.routers.prom.rule=Host(`${PROMETHEUS_FQDN}`)"
      - "traefik.http.routers.prom.entrypoints=websecure"
      - "traefik.http.routers.prom.tls=true"
      - "traefik.http.routers.prom.tls.certresolver=le"
      - "traefik.http.services.prom.loadbalancer.server.port=9090"
      - "traefik.http.routers.prom.middlewares=prom-auth@docker"
      - "traefik.http.middlewares.prom-auth.basicauth.usersfile=${TRAEFIK_USERSFILE}"

  grafana:
    profiles: ["monitoring"]
    image: grafana/grafana:latest
    restart: unless-stopped
    environment:
      - TZ=${GENERIC_TIMEZONE}
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=${MONITORING_BASIC_AUTH_PASS}
      - GF_SERVER_DOMAIN=${GRAFANA_FQDN}
      - GF_SERVER_ROOT_URL=https://${GRAFANA_FQDN}
      - GF_SERVER_ENFORCE_DOMAIN=true
      - GF_SECURITY_COOKIE_SECURE=true
      - GF_USERS_ALLOW_SIGN_UP=false
      - GF_PATHS_PROVISIONING=/etc/grafana/provisioning
    volumes:
      - grafana-data:/var/lib/grafana
      - ./monitoring/grafana/provisioning/datasources:/etc/grafana/provisioning/datasources:ro
      - ./monitoring/grafana/provisioning/dashboards:/etc/grafana/provisioning/dashboards:ro
      - ./monitoring/grafana/provisioning/alerts:/etc/grafana/provisioning/alerts:ro
    networks: [n8n-network]
    security_opt: [no-new-privileges:true]
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=n8n-network"
      - "traefik.http.routers.grafana.rule=Host(`${GRAFANA_FQDN}`)"
      - "traefik.http.routers.grafana.entrypoints=websecure"
      - "traefik.http.routers.grafana.tls=true"
      - "traefik.http.routers.grafana.tls.certresolver=le"
      - "traefik.http.services.grafana.loadbalancer.server.port=3000"
      - "traefik.http.routers.grafana.middlewares=grafana-auth@docker,secure-headers@docker"
      - "traefik.http.middlewares.grafana-auth.basicauth.usersfile=${TRAEFIK_USERSFILE}"
      - "traefik.http.middlewares.grafana-auth.basicauth.removeheader=true"
      - "traefik.http.middlewares.secure-headers.headers.stsSeconds=31536000"
      - "traefik.http.middlewares.secure-headers.headers.stsIncludeSubdomains=true"
      - "traefik.http.middlewares.secure-headers.headers.stsPreload=true"
      - "traefik.http.middlewares.secure-headers.headers.browserXssFilter=true"
      - "traefik.http.middlewares.secure-headers.headers.contentTypeNosniff=true"
    depends_on: [prometheus]

  postgres-exporter:
    profiles: ["monitoring"]
    image: quay.io/prometheuscommunity/postgres-exporter:latest
    restart: unless-stopped
    environment:
      - DATA_SOURCE_NAME=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?sslmode=disable
    networks: [n8n-network]
    security_opt: [no-new-privileges:true]
    depends_on:
      postgres:
        condition: service_healthy

  cadvisor:
    profiles: ["monitoring"]
    image: gcr.io/cadvisor/cadvisor:latest
    restart: unless-stopped
    privileged: true
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /var/lib/docker/:/var/lib/docker:ro
    networks: [n8n-network]
    security_opt: [no-new-privileges:true]

  node-exporter:
    profiles: ["monitoring"]
    image: prom/node-exporter:latest
    restart: unless-stopped
    pid: "host"
    networks: [n8n-network]
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /:/rootfs:ro
    command:
      - "--path.procfs=/host/proc"
      - "--path.sysfs=/host/sys"
      - "--path.rootfs=/rootfs"
    security_opt: [no-new-privileges:true]

networks:
  n8n-network:
    name: n8n-network
    driver: bridge

volumes:
  n8n-data:
    external: true
  postgres-data:
    external: true
  letsencrypt:
    external: true
  prometheus-data:
    external: true
  grafana-data:
    external: true

Create the .env configuration file

Copy the .env file here or from my GitHub single-mode/.env and then update the values for your own DOMAIN, SSL_EMAIL, GENERIC_TIMEZONE, N8N_ENCRYPTION_KEY, and some Strong Passwords:

Example .env file 
# ================================================
#    ENV VARIABLES FOR SINGLE MODE & MONITORING
# ================================================

# -------- DOMAIN & FQDN --------
DOMAIN=example.com
SUBDOMAIN_N8N=n8n-test
SUBDOMAIN_GRAFANA=grafana
SUBDOMAIN_PROMETHEUS=prometheus
SSL_EMAIL=[email protected]
GENERIC_TIMEZONE=Asia/Ho_Chi_Minh

N8N_FQDN=${SUBDOMAIN_N8N}.${DOMAIN}
GRAFANA_FQDN=${SUBDOMAIN_GRAFANA}.${DOMAIN}
PROMETHEUS_FQDN=${SUBDOMAIN_PROMETHEUS}.${DOMAIN}

# -------- IMAGE & RUNTIME --------
N8N_IMAGE_TAG=latest
NODE_ENV=production
N8N_LOG_LEVEL=info
N8N_DIAGNOSTICS_ENABLED=false
N8N_BLOCK_ENV_ACCESS_IN_NODE=true

# -------- n8n URLS --------
N8N_PORT=5678
N8N_PROTOCOL=https
N8N_HOST=${N8N_FQDN}
WEBHOOK_URL=https://${N8N_FQDN}
N8N_EDITOR_BASE_URL=https://${N8N_FQDN}
N8N_PUBLIC_API_BASE_URL=https://${N8N_FQDN}
N8N_SECURE_COOKIE=true

# -------- SECURITY & SECRETS --------
# Generate with: openssl rand -base64 16
POSTGRES_PASSWORD=CHANGE_ME_BASE64_16_BYTES
# Generate with: openssl rand -base64 32
N8N_ENCRYPTION_KEY=CHANGE_ME_BASE64_32_BYTES
# Generate with: openssl rand -base64 16
N8N_BASIC_AUTH_PASSWORD=CHANGE_ME_BASE64_16_BYTES

N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
N8N_BASIC_AUTH_ACTIVE=true
N8N_BASIC_AUTH_USER=admin
# N8N_BASIC_AUTH_PASSWORD=${N8N_BASIC_AUTH_PASSWORD}

# -------- DATABASE SETTINGS --------
DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=postgres
DB_POSTGRESDB_PORT=5432
DB_POSTGRESDB_DATABASE=n8n
DB_POSTGRESDB_USER=n8n
DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD}

POSTGRES_USER=n8n
# POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
POSTGRES_DB=n8n

# -------- RUNNERS (internal) --------
N8N_RUNNERS_ENABLED=true
N8N_RUNNERS_MODE=internal
N8N_RUNNERS_MAX_CONCURRENCY=5
N8N_RUNNERS_AUTH_TOKEN=${N8N_BASIC_AUTH_PASSWORD}

# -------- EXECUTION BEHAVIOR --------
EXECUTIONS_DATA_PRUNE=true
EXECUTIONS_DATA_MAX_AGE=336
EXECUTIONS_RETRY_MAX=3

# -------- MONITORING STACK --------
COMPOSE_PROJECT_NAME=n8n
COMPOSE_PROFILES=
TRAEFIK_USERSFILE=/etc/traefik/htpasswd
MONITORING_BASIC_AUTH_USER=admin
# Grafana admin password and Traefik’s Basic Auth
MONITORING_BASIC_AUTH_PASS=n8nToolKit@2ai4$
EXPOSE_PROMETHEUS=false

# -------- END OF CONFIG --------

Edit the top of your /home/n8n/.env file:

DOMAIN=yourdomain.com
SUBDOMAIN_N8N=n8n
SSL_EMAIL=[email protected]
GENERIC_TIMEZONE=Asia/Ho_Chi_Minh   # or your TZ
  • Generate strong secrets and write them into /home/n8n/.env file:
PG=$(openssl rand -base64 16)
REDIS=$(openssl rand -base64 16)
KEY=$(openssl rand -base64 32)
BASIC=$(openssl rand -base64 16)

# Update the placeholders in .env
sed -i \
 -e "s|^POSTGRES_PASSWORD=.*|POSTGRES_PASSWORD=$PG|" \
 -e "s|^REDIS_PASSWORD=.*|REDIS_PASSWORD=$REDIS|" \
 -e "s|^N8N_ENCRYPTION_KEY=.*|N8N_ENCRYPTION_KEY=$KEY|" \
 -e "s|^N8N_BASIC_AUTH_PASSWORD=.*|N8N_BASIC_AUTH_PASSWORD=$BASIC|" \
 .env

Step 4: Launch the n8n stack

# Make sure you are in the target directory
cd /home/n8n

# Create a directory called local-files for sharing files between the n8n instance and the host system
mkdir -p ./local-files
# Let your host user own the folder; n8n runs as user 1000 in the container
chown -R ${SUDO_USER:-$USER}:${SUDO_USER:-$USER} ./local-files
chmod 755 ./local-files

# Validate YAML & env expansion first
docker compose config

# Pull images (optional but recommended)
docker compose pull

# Manual create volume
for v in n8n-data postgres-data letsencrypt; do docker volume create "$v"; done
docker volume ls | grep -E 'n8n-data|postgres-data|letsencrypt'

# Start everything (Traefik, Postgres, n8n)
docker compose -f docker-compose.yml up -d

# Check health
docker ps --format "table {{.Names}}\t{{.Status}}"

# Example logs:
# NAMES      STATUS
# n8n        Up 19 seconds (healthy)
# postgres   Up 26 seconds (healthy)
# traefik    Up 26 seconds (healthy)

The Docker Compose file runs three main containers:

  • n8n, the automation app itself.
  • Traefik, the reverse proxy that terminates TLS/SSL certificates and routes HTTPS traffic to n8n.
  • PostgreSQL, the database container for storing workflows, credentials, and execution history.

It also creates and mounts persistent storage volumes:

NameTypeContainer MountPurpose
n8n-dataVolume/home/node/.n8nStores encryption keys, user sessions, and small metadata.
postgres-dataVolume/var/lib/postgresql/dataStores the PostgreSQL database files (all workflows, credentials, etc.).
letsencryptVolume/letsencryptStores TLS/SSL certificates managed by Traefik.
./local-filesBind/filesA shared folder between host and n8n. Useful for importing/exporting files inside workflows.

We use external volumes (named Docker volumes) instead of internal container storage so that:

  • Data survives container recreation (upgrades, restarts, rebuilds).
  • You can backup and restore volumes independently of the running containers.
  • Multiple script runs won’t accidentally wipe your database or certificates.

What about ./local-files (bind mount)?

This maps a folder from the host server filesystem into the container to let workflows read/write files at /files inside n8n, while actually persisting them on the host at ./local-files.

  • Example: upload/download files via workflows, process CSV/JSON, or generate reports into /files.
  • Since it maps to a host folder (./local-files), you can open those files directly on your VPS.

Step 5: Verify the installation

  • Visit: https://n8n.yourdomain.com
  • Confirm SSL is active (green padlock in the browser).

🎉 Congratulations,you now have a production-ready n8n instance running on Ubuntu with Docker!

Step 6: First-Time Setup & License Activation

Now, open your browser and visit your n8n instance at the domain or hostname you configured (e.g https://n8n.nextgrowth.ai). You’ll be greeted with the n8n owner account setup page, where you can create your admin account with secure credentials.

n8n owner account setup page for creating admin credentials after installation

After creating your owner account, n8n will show a short onboarding form to help tailor the experience. This step is optional and only helps n8n understand its users better. Once you’ve filled it out, click Get started.

n8n onboarding customization form displayed after initial account setup

Next, you’ll see a page offering a free license key for some advanced features:

n8n free license key activation page with email signup form

To activate, simply enter your email and click Send me a free license key. You’ll receive a key by email that unlocks these features permanently.

After submitting your email, you’ll receive an email from n8n containing your license key.

To activate:

  1. Copy the license key from the email.
  2. In your n8n dashboard, go to Settings → Usage → Plan.
  3. Paste the key into the activation field.

Your advanced features will now be permanently unlocked for your instance.

How to Upgrade n8n instance

Like any software, keeping n8n updated is critical for security, bug fixes, and new features. With Docker, upgrading is straightforward if you follow the right steps. One warning before you run docker compose pull in 2026: this stack pins N8N_IMAGE_TAG=latest, and latest now resolves to the 2.x line. n8n 2.0.0 (released 2025-12-05) is a hardening release with breaking changes, several of which hit a self-hosted Docker setup directly: task runners are enabled by default, environment-variable access is blocked from Code nodes, the Execute Command and Local File Trigger nodes are disabled by default, and in-memory binary data mode has been removed. n8n publishes a Migration Report tool to tell you which of your own workflows are affected. The safe sequence is: back up first (next section), pin N8N_IMAGE_TAG to your current version so you can roll back, run the migration report, and only then move to latest. Note that this guide already sets N8N_BLOCK_ENV_ACCESS_IN_NODE=true, so the env-access change will not surprise you here.

# Navigate to the directory containing your docker compose file
cd /home/n8n

# Check your current n8n version
docker exec n8n n8n --version

# Pull latest version
docker compose pull

# Stopping and removing existing containers
docker compose down

# Restart the Stack
docker compose up -d

# Check health
docker ps --format "table {{.Names}}\t{{.Status}}"
# Example logs:
# NAMES      STATUS
# n8n        Up 21 seconds (healthy)
# postgres   Up 28 seconds (healthy)
# traefik    Up 28 seconds (healthy)

# Check your current n8n version to see new version
docker exec n8n n8n --version

Upgrading from n8n 1.x to 2.x

If your instance predates December 2025, the upgrade above crosses a major version rather than a patch. n8n 2.0 is a hardening release, and five of its changes break configurations that were correct on 1.x. This is the table the toolkit itself is built against.

Four-step n8n upgrade sequence from 1.x to 2.x: back up, pin the current version, run the migration report, then upgrade
What changed1.x2.x
Task runnerbundled in the n8n containerinternal subprocess, enabled by default
Execution modeEXECUTIONS_PROCESSEXECUTIONS_MODE=regular|queue
Stalled job configQUEUE_WORKER_MAX_STALLED_COUNTremoved
Config filesN8N_CONFIG_FILESremoved, use environment variables
Env access in the Code nodeallowed by defaultblocked by default (N8N_BLOCK_ENV_ACCESS_IN_NODE=true)

The last row is the one that bites hardest, because nothing errors. A Code node that read $env simply stops seeing values, and a workflow that built a URL that way keeps running while quietly emitting the fallback. Run the n8n Migration Report from Settings first, and pin your current version before you upgrade so you have a way back.

Check the instance before you trust it: –doctor

One failure mode is worth the whole command, and n8n’s own documentation does not cover it: an active workflow whose webhook never registered answers 404 on its production /form/ URL while the editor still shows it live. Nothing is red. The only way to see it is to ask the database whether a row exists in webhook_entity for every active workflow, which is one of the things --doctor does.

The four sections an n8n --doctor run reports on: health, security, legacy config and webhook registration
sudo ./n8n_manager.sh --doctor -d /home/n8n

It is read-only and changes nothing. It prints the verdict first (FAIL, WARN or PASS with counts), then the detail by section, then a block you can paste into a bug report with every secret masked. The exit code is 0 when nothing failed and 1 otherwise, so it works as a cron health check.

SectionWhat it checks
Healthstack files, mode, n8n version, per-service container state and health, free disk
Securityencryption key still the shipped placeholder, .env readable beyond its owner, n8n below the CVE patch floor, the n8n port published on all interfaces, .env tracked by git, backups uploaded unencrypted, alert rules with no contact point
Legacydead N8N_BASIC_AUTH_* keys, a pre-v3.1 compose file still reading ${N8N_VERSION}
Webhooksfor each active workflow, whether a row exists in webhook_entity

The CVE patch floors it compares against come from the NVD records rather than press coverage: 1.123.22 for the 1.x line and 2.10.1 for 2.x. If you are below either, the security section fails rather than warns.

One of those security findings deserves calling out, because it is the most common way a monitoring setup gives false comfort. The monitoring profile ships 14 Grafana alert rules with thresholds tuned for n8n: event-loop p99 at 250 ms and 500 ms, RSS at 850 MiB, API error ratio at 2% and 5%, queue backlog, version skew, and the one people forget, queue active but throughput near zero. Until you give those rules a contact point, they evaluate on schedule and notify nobody. Wire delivery at install with --alerts telegram --alert-target '<bot-token>:<chat-id>', and note that --doctor flags rules that exist with no delivery configured.

How to Backup your n8n instance

Before you upload a backup anywhere, know what is inside it. The archive contains your .env, which means N8N_ENCRYPTION_KEY plus the database and Redis passwords, alongside a full PostgreSQL dump. Sent to cloud storage unencrypted, anyone who can read that bucket can decrypt every credential in the instance.

BACKUP_PASSPHRASE='...' sudo -E ./n8n_manager.sh -b --encrypt -s gdrive:/n8n-backups

--encrypt wraps the archive with gpg --symmetric --cipher-algo AES256. The passphrase is read from BACKUP_PASSPHRASE in the environment so the key does not sit on the machine holding the data it protects, and it is never generated for you, because a backup encrypted with a key you do not hold is not a backup. Restore detects a .gpg archive and decrypts it before anything else runs.

Schedule it, or it will not happen

A backup you run by hand is a backup you stop running. Two ways to automate it, and the difference between them matters more than it looks.

n8n backup lifecycle loop: create the backup, encrypt it, upload it off-site, verify the archive, then restore

Cron is the shorter path. Write a small wrapper so cron has the environment it needs, then schedule it:

# /opt/n8n-toolkit/run_backup.sh
export SMTP_USER="[email protected]"
export SMTP_PASS="your_app_password"
/opt/n8n-toolkit/n8n_manager.sh -b -d /home/n8n -s gdrive:/n8n-backups   -e [email protected] --notify-on-success "$@" >> /opt/n8n-toolkit/logs/cron.log 2>&1

# crontab -e
0 2 * * * /opt/n8n-toolkit/run_backup.sh
15 2 * * 0 /opt/n8n-toolkit/run_backup.sh -f

The Sunday line adds -f to force a backup even when nothing changed, so you always hold at least one archive per week. Backups skip by default when the instance has not changed, which keeps storage sane but also means a quiet week produces nothing.

A systemd timer survives reboots, which is the reason to prefer it on a server you actually care about. Run the same command as a Type=oneshot service with Environment= lines for the SMTP credentials and StandardOutput=append: pointing at a log file, then enable a matching timer. Cron will not fire a job it missed while the box was down; a timer with Persistent=true will.

Your automation infrastructure is only as reliable as your maintenance plan. A production setup requires a solid strategy for backups and a safe process for updates.

A Simple Backup Strategy:

With our volume-based setup, backing up is straightforward. You simply need to archive the contents of the Docker volumes. This n8n docker backup strategy can be run periodically via a cron job.

Execute these commands from your host machine to create a compressed backup of your n8n and PostgreSQL data:

# Navigate to the directory containing your docker compose file
cd /home/n8n

# Check containers are healthy before backup
docker ps --format "table {{.Names}}\t{{.Status}}"

# Make suare all container up and running

# Create backup folder
DATE=$(date +%F_%H-%M-%S)
BACKUP_DIR=/home/n8n/backups/backup_$DATE
mkdir -p "$BACKUP_DIR"

# Backup volumes
for vol in n8n-data postgres-data letsencrypt; do
  docker run --rm \
    -v ${vol}:/data \
    -v "$BACKUP_DIR:/backup" \
    alpine sh -c "tar czf /backup/volume_${vol}_$DATE.tar.gz -C /data ."
done

# Backup bind mount volume
tar -czf local-files_backup_$DATE.tar.gz -C /home/n8n local-files

# Dump PostgreSQL database
docker exec postgres pg_dump -U n8n -d n8n > "$BACKUP_DIR/n8n_postgres_dump_$DATE.sql"

# Backup config files
cp /home/n8n/.env "$BACKUP_DIR/.env.bak"
cp /home/n8n/docker-compose.yml "$BACKUP_DIR/docker-compose.yml.bak"

# Compress everything into one archive
tar -czf "/home/n8n/backups/n8n_backup_$DATE.tar.gz" -C "$BACKUP_DIR" .

# Generate checksum (optional)
sha256sum "/home/n8n/backups/n8n_backup_$DATE.tar.gz" > "/home/n8n/backups/n8n_backup_$DATE.tar.gz.sha256"

# Check your backup folder to see the tarball files
ls /home/n8n/backups

# Get the full path of backup tarball
ls /home/n8n/backups/n8n_backup_$DATE.tar.gz

How to Restore the n8n instance

In case of system failure or migration, you can restore your n8n stack from backups.

# Navigate to the directory containing your docker compose file
cd /home/n8n

# Extract the archive
RESTORE_DIR=/home/n8n/restore_$(date +%s)
mkdir -p "$RESTORE_DIR"
tar -xzf /home/n8n/backups/n8n_backup_<timestamp>.tar.gz -C "$RESTORE_DIR"

ll "$RESTORE_DIR"
# Now inside $RESTORE_DIR you’ll have:
  # local-files_backup_*.tar.gz
  # volume_n8n-data_*.tar.gz
  # volume_postgres-data_*.tar.gz (or just a SQL dump)
  # volume_letsencrypt_*.tar.gz
  # n8n_postgres_dump_*.sql (if backup included it)
  # .env.bak and docker-compose.yml.bak
  
# Stop the current stack  
docker compose down --volumes --remove-orphans

# Restore .env and docker-compose.yml
cp -f "$RESTORE_DIR/.env.bak" /home/n8n/.env
cp -f "$RESTORE_DIR/docker-compose.yml.bak" /home/n8n/docker-compose.yml

# Restore bind mount volume

tar -xzf "$RESTORE_DIR"/local-files_backup_<timestamp>..tar.gz -C /home/n8n

# Restore external docker volumes
# Only restore volumes (n8n-data, letsencrypt)
for vol in n8n-data letsencrypt; do   # omit postgres-data if using SQL dump
  VOL_FILE=$(find "$RESTORE_DIR" -name "volume_${vol}_*.tar.gz" -print -quit)
  if [[ -n "$VOL_FILE" ]]; then
    docker volume rm -f $vol 2>/dev/null || true
    docker volume create $vol
    docker run --rm -v ${vol}:/data -v "$RESTORE_DIR:/backup" alpine \
      sh -c "rm -rf /data/* && tar xzf /backup/$(basename $VOL_FILE) -C /data"
    echo "[OK] Restored $vol"
  fi
done

# Start Postgres first
docker compose up -d postgres

# Check if postgres in healthy status
docker inspect --format='{{.State.Health.Status}}' postgres

# Drop & recreate the database
DB_NAME=n8n
DB_USER=n8n
docker exec -i postgres psql -U $DB_USER -d postgres -v ON_ERROR_STOP=1 -c \
"SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname='${DB_NAME}' AND pid <> pg_backend_pid();"

docker exec -i postgres psql -U $DB_USER -d postgres -v ON_ERROR_STOP=1 -c "DROP DATABASE IF EXISTS ${DB_NAME};"
docker exec -i postgres psql -U $DB_USER -d postgres -v ON_ERROR_STOP=1 -c "CREATE DATABASE ${DB_NAME} OWNER ${DB_USER};"
docker exec -i postgres psql -U $DB_USER -d $DB_NAME < $RESTORE_DIR/n8n_postgres_dump_*.sql

# Start the full stack
docker compose up -d

# Check health
docker ps --format "table {{.Names}}\t{{.Status}}"
# Example logs:
# NAMES      STATUS
# traefik    Up 37 seconds (healthy)
# n8n        Up 37 seconds (healthy)
# postgres   Up About a minute (healthy)

⚠️ Best Practices

  • Automate backups (cron + script) for daily or weekly snapshots.
  • Test restores periodically to verify data integrity.
  • Keep multiple versions (30-day rolling window recommended).
  • Store copies in secure, redundant locations.

Frequently Asked Questions

What’s the best way to install n8n on Ubuntu for production?

The recommended method is Docker Compose. This isolates n8n and its dependencies (like PostgreSQL) in containers, making upgrades, scaling, and backups much easier. With Docker Compose, you can also define environment variables, persistent storage, and restart policies,ensuring your n8n instance is robust and production-ready.

What are the minimum server requirements for self-hosting n8n?

As a solid starting point for moderate use, we recommend a server with at least 1 vCPU, 2GB of RAM, and 20GB of storage. However, your actual requirements will scale with the complexity and frequency of your workflows. Workflows that process large amounts of data or run very frequently will require more CPU and RAM.

How do I secure my n8n instance on Ubuntu with HTTPS?

Use a reverse proxy (Traefik recommended, though Nginx or Caddy also work). Pair it with Let’s Encrypt for free SSL certificates. This ensures all traffic between users and your automation platform is encrypted. Also:

  • Set strong credentials.
  • Restrict access to the admin interface.
  • Keep your containers updated to patch vulnerabilities.

Do I need a separate database for n8n on Ubuntu?

Yes,PostgreSQL is strongly recommended for production. Unlike SQLite (default), PostgreSQL ensures:

  • Better persistence and reliability.
  • Support for scaling and queue mode.
  • Safer backups and easier migrations.

Can I use MySQL instead of PostgreSQL?

No, not any more. n8n 2.0 dropped MySQL and MariaDB as storage backends, support that had been deprecated since 1.0, so DB_TYPE=mysqldb is no longer a path forward. PostgreSQL is the recommendation for production and SQLite remains supported for small installs. If you are on MySQL or MariaDB today, n8n asks you to move the data to PostgreSQL or SQLite with its database migration tool before upgrading to 2.0, not after. Our guide to upgrading n8n without losing data covers that sequence, and n8n states the removal in its 2.0 breaking changes (checked 2026-09-04).

What common mistakes should I avoid when self-hosting n8n?

  • Using SQLite in production
  • Skipping reliable backup strategies
  • Lacking error monitoring
  • Over-relying on third-party AIs or automated advice. These errors can lead to data loss, downtime, or costly failures.

Why might webhooks fail in a self-hosted setup?

If n8n doesn’t know its public address (missing WEBHOOK_URL), it can generate incorrect local URLs like localhost:5678 that external services can’t reach. Make sure this variable matches your external domain.

How do I recover if the server goes down or I lose data?

You’ll need to rely on your backup strategy: PostgreSQL dumps, backups of volumes, SSL certs, .env, and Compose files. These let you restore quickly. Without backups, you risk permanent data loss and prolonged downtime.

Resources

Extending Your n8n Setup

Once your n8n instance is running, you’ll likely need to connect it to external services. Three common integrations worth bookmarking: WordPress Application Passwords for n8n, Cloudflare R2 integration with n8n, and updating Rank Math via n8n REST API.

Conclusion

You’ve successfully journeyed from a simple local n8n instance to a secure, persistent, and production-ready automation powerhouse. By following this tiered blueprint, you have built a foundation that avoids the most common and costly pitfalls of self-hosting. You now have a system that protects your data, secures your connections, and is ready for serious automation tasks.

Understanding the core principles of data persistence with volumes, robust database management with PostgreSQL, and ironclad security with a reverse proxy is the key difference between a temporary toy project and a reliable business asset. You’ve not only deployed n8n; you’ve mastered the architecture required to run it professionally.

You’ve now mastered the blueprint for a robust self-hosted n8n instance. If you’d rather focus on building workflows than managing infrastructure, explore how our managed solution handles all of this,and more,for you automatically.

This article is part of our broader pillar guide. For the full context, see our what is n8n (n8n cluster hub).

Avatar

I’m The Nguyen. 10 years as a DevOps engineer taught me one thing that changed how I do SEO: if it’s not automated, monitored, and recoverable, it’s not production-ready. I build n8n workflows that meet that standard — keyword research, competitor analysis, content pipelines, rank tracking. Read more →

Related Posts