n8n Self-Hosted with Docker: The Complete Installation Guide

Figure 1: A production-ready n8n instance, running entirely on your own server.

💡 Every Docker install guide for n8n stops at "it's running." None of them tell you what breaks the moment you actually start using it — the webhook that shows localhost, the workflow data that vanishes after a restart, the timezone that silently throws off every scheduled automation. This guide gets you running the production-ready way from the first command, and then covers exactly what to do about the eight things that go wrong next.

🔥 I self-host every workflow on this site's Templates library on the exact stack in this guide — Docker Compose, Postgres, persistent volumes, the works. Every error section below is something that actually happened on a real server, not a theoretical edge case copied from documentation. Whether you're setting up your first VPS or you've done this a dozen times and just want the config file, this guide is built to work for both.

1. Docker vs npm vs n8n Cloud — Pick the Right One First

Before touching a terminal, decide which installation path actually fits your situation. Getting this wrong means redoing the setup later.

This guide focuses entirely on Docker because it's the option most people searching for a real, ongoing self-hosted setup actually need — and because it's the same stack this site's own automations and every downloadable template in the Workflow Templates library assumes you're running.

There's also a cost dimension worth being explicit about, in the same spirit as this site's Zero-Budget Lead Pipeline guide: n8n Cloud's starter tier runs roughly $20/month with capped executions, while a small VPS capable of running the Docker stack in this guide typically costs $5-10/month with no execution ceiling at all. For anyone running the automations this site covers — lead pipelines, invoice reminders, AI content workflows — that difference compounds fast once you're past the trial stage.

2. Prerequisites

• A VPS or server running Linux (Ubuntu 22.04 or newer is the most widely documented and supported choice).
• At least 1GB of RAM for light use; 2GB or more recommended once you're also running Postgres alongside n8n, which this guide's setup does.
• Docker and Docker Compose installed. Since Docker Engine 20.10, Compose ships as a plugin (docker compose, no hyphen), so a separate install usually isn't needed on a recent Docker version.
• A domain name pointed at your server's IP. Not strictly required to get a container running, but required for webhooks, OAuth-based credentials, and HTTPS to actually work — which means you'll need it very soon regardless.

Any mainstream VPS provider works fine here — n8n and Postgres together aren't resource-hungry at small scale. A budget 2GB RAM / 1 vCPU plan is a reasonable starting point for personal or small-team use; you can always resize later since the entire stack lives in Docker volumes, not tied to any specific server instance. If you're choosing between providers, prioritize ones with straightforward snapshot/backup features over marginal price differences — restoring from a snapshot after something goes wrong is worth far more than saving a couple of dollars a month.

3. Step-by-Step Installation

Figure 2: The n8n owner account setup screen — your signal that the container stack is running correctly.

A Note on HTTPS and Reverse Proxies

Reaching n8n over plain HTTP on port 5678 works for a first test, but production use — and specifically anything involving OAuth credentials like Google or LinkedIn — requires HTTPS on a real domain. The standard approach is a reverse proxy (Caddy, Nginx, or Traefik) sitting in front of n8n, handling TLS certificates automatically and forwarding traffic to the container. Caddy is the simplest to get running correctly on a first attempt, since it issues and renews Let's Encrypt certificates with almost no manual configuration:

n8n.yourdomain.com {
    reverse_proxy localhost:5678
}

That's the entire configuration for a working HTTPS setup with Caddy — it handles the certificate issuance and renewal on its own. Nginx and Traefik accomplish the same result with more configuration but finer control, and are worth considering once you're running more than a single service on the same server. A full walkthrough of hardening this setup (rate limiting, security headers, multi-service routing) is deliberately out of scope here — it deserves its own dedicated guide rather than a rushed afterthought in an installation article.

4. Postgres vs SQLite — Don't Skip This Decision

n8n defaults to SQLite if you don't configure a database at all. Most quick-start tutorials leave it there because it requires zero extra setup. That default is fine for a five-minute test — it's the wrong choice for anything you actually intend to rely on.

Backing Up Your Data

With Postgres in the stack, backups are a standard database dump rather than hoping you remember to copy a single SQLite file. Run this from your host to produce a portable backup you can store off-server:

docker compose exec postgres pg_dump -U n8n -d n8n > n8n_backup_$(date +%Y%m%d).sql

Schedule this as a cron job on the host, and store the resulting file somewhere other than the same server — a backup that lives only on the machine it's backing up doesn't protect you from that machine failing.

Figure 3: Postgres adds one extra service to your stack in exchange for reliability SQLite can't match under real load.

5. The Next Problem You'll Hit (And Where to Fix It)

Here's what almost every Docker installation guide leaves out: getting the container running is not the same as having a working n8n instance. The single most common next issue, the moment you try to use a webhook-triggered workflow, is that the webhook URL shows localhost instead of your real domain — even though n8n is clearly running and reachable.

If you're building your first real workflow after this install, the What is a Webhook guide is the natural next stop — it explains the concept this exact error is about, from zero.

6. 8 Common Errors During and After Installation

Most installation problems fall into one of three buckets: something about the environment configuration is missing or wrong, data persistence wasn't set up correctly, or a startup ordering issue caused a race condition between services. Knowing which bucket you're in narrows troubleshooting fast — check the logs first with docker compose logs -f before assuming the worst, since the actual error message usually points directly at one of the eight causes below.

A Worked Diagnostic Example

Say your n8n container shows as "running" in docker compose ps, but the browser just times out. Walk it in order: first, docker compose logs n8n — if it shows a successful startup with no errors, the problem is almost certainly network-level (firewall, security group, or DNS), not n8n itself. If the logs instead show a database connection error, check docker compose ps for Postgres specifically — if it's still starting or unhealthy, that's Error 7, and n8n is correctly refusing to run against a database that isn't ready yet. This kind of layered check — logs, then service health, then network — resolves the large majority of "it's just not working" reports faster than guessing at configuration changes one at a time.

7. Updating n8n Safely (Without Losing Data)

As long as your data lives in named volumes — which the config in this guide sets up by default — updating is low-risk. The sequence matters, though.

cd n8n-docker
docker compose pull
docker compose up -d
docker compose logs -f n8n

Watch the logs after updating to confirm n8n starts cleanly before you consider the update finished. If something looks wrong, you can roll back by pinning the image tag in docker-compose.yml to the previous version and running up -d again.

If you're running anything business-critical, it's worth testing an update against a staging copy before touching production — even a second, temporary Docker Compose stack pointed at a copy of your data, torn down after the test. That's more setup than most personal automations need, but for a workflow that a client or team depends on, an hour of caution before an update beats an afternoon of recovery after one.

8. Complete Downloadable Configuration

This is the exact docker-compose.yml and .env pair referenced throughout this guide — Postgres included, healthcheck-gated startup, persistent volumes, and every environment variable from the error section already set correctly.

version: "3.8"

services:
  postgres:
    image: postgres:16
    restart: always
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 10

  n8n:
    image: docker.n8n.io/n8nio/n8n
    restart: always
    ports:
      - "5678:5678"
    environment:
      - N8N_HOST=${N8N_HOST}
      - N8N_PROTOCOL=https
      - N8N_PORT=5678
      - WEBHOOK_URL=https://${N8N_HOST}/
      - GENERIC_TIMEZONE=${GENERIC_TIMEZONE}
      - TZ=${GENERIC_TIMEZONE}
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=${N8N_BASIC_AUTH_USER}
      - N8N_BASIC_AUTH_PASSWORD=${N8N_BASIC_AUTH_PASSWORD}
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=${POSTGRES_DB}
      - DB_POSTGRESDB_USER=${POSTGRES_USER}
      - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD}
    volumes:
      - n8n_data:/home/node/.n8n
      - ./local-files:/files
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  postgres_data:
  n8n_data:

POSTGRES_USER=n8n
POSTGRES_PASSWORD=change_this_password
POSTGRES_DB=n8n

N8N_HOST=n8n.yourdomain.com
GENERIC_TIMEZONE=Africa/Tunis

N8N_BASIC_AUTH_USER=admin
N8N_BASIC_AUTH_PASSWORD=change_this_password

9. Frequently Asked Questions

Continue Your n8n Journey