dankhostself-host anything

n8n with Docker Compose

n8n is a workflow automation platform that uniquely combines AI capabilities with business process automation, giving technical teams the flexibility of code with the speed of no-code. In the project's words: n8n.io front page checked 2026-09-25

Runs on: amd64, arm64 from each image's registry manifest, checked 2026-10-01; a CPU counts only if every image has a build for it. Image by image

Add n8n to the builder to use your own domain and combine it with other apps in one file.

What n8n needs

Only figures n8n's own documentation publishes, each linked to the page it is on. Where the project gives no number, this page does not invent one.

ResourceMinimumRecommended
RAMThe project publishes no figure
No figure is published. n8n does not limit how much data a node fetches, so memory grows with the workflows: many nodes, big items, the Code node and manual runs (which keep a copy for the editor) all raise it. Source: n8n docs: Fix memory issues checked 2026-09-25
CPUThe project publishes no figure
DiskThe project publishes no figure

On top of this, Caddy (the reverse proxy in the file) is a single small container. n8n itself runs as 1 container with SQLite (n8n) or 2 containers with PostgreSQL (n8n-postgres, n8n) or 6 containers with PostgreSQL and Redis in queue mode (n8n-postgres, n8n-redis, n8n, n8n-runner, n8n-worker, n8n-worker-runner).

Which hardware n8n has images for

Read from each image's manifest list in its registry (anonymous, read-only) when this page was built. An app counts for a CPU only if every one of its images lists it.

With SQLite, the default

  • x86-64 PC or NAS (linux/amd64): every image has a build.
  • Raspberry Pi 4/5, 64-bit OS (linux/arm64): every image has a build.
  • Raspberry Pi 3 or Zero 2 W, 32-bit OS (linux/arm/v7): no image for n8n. No image for this hardware; the builder leaves the app out.
ServiceImagePlatforms in the manifestDigestRegistryChecked
n8nn8nio/n8namd64, arm64sha256:ffeb52485f78b1b06c9a832205853cf75da72a07a514c9a27724df85979d6c34registry-1.docker.io2026-09-25

With PostgreSQL

  • x86-64 PC or NAS (linux/amd64): every image has a build.
  • Raspberry Pi 4/5, 64-bit OS (linux/arm64): every image has a build.
  • Raspberry Pi 3 or Zero 2 W, 32-bit OS (linux/arm/v7): no image for n8n. No image for this hardware; the builder leaves the app out.
ServiceImagePlatforms in the manifestDigestRegistryChecked
postgrespostgres:18amd64, arm/v5, arm/v7, arm64, 386, ppc64le, riscv64, s390xsha256:5a5a84b19854a9ffaa54082c166ff4ec27473a361e496e5ea167f298f2da9722registry-1.docker.io2026-09-25
n8nn8nio/n8namd64, arm64sha256:ffeb52485f78b1b06c9a832205853cf75da72a07a514c9a27724df85979d6c34registry-1.docker.io2026-09-25

With PostgreSQL + workers (queue mode)

  • x86-64 PC or NAS (linux/amd64): every image has a build.
  • Raspberry Pi 4/5, 64-bit OS (linux/arm64): every image has a build.
  • Raspberry Pi 3 or Zero 2 W, 32-bit OS (linux/arm/v7): no image for n8n, n8n-runner, n8n-worker, n8n-worker-runner. No image for this hardware; the builder leaves the app out.
ServiceImagePlatforms in the manifestDigestRegistryChecked
postgrespostgres:18amd64, arm/v5, arm/v7, arm64, 386, ppc64le, riscv64, s390xsha256:5a5a84b19854a9ffaa54082c166ff4ec27473a361e496e5ea167f298f2da9722registry-1.docker.io2026-09-25
redisredis:7-alpineamd64, arm/v6, arm/v7, arm64, 386, ppc64le, riscv64, s390xsha256:858f009f9709ce576febc734aa78b8f6d624b82571f9ddb6bda4377c833b3499registry-1.docker.io2026-10-01
n8ndocker.n8n.io/n8nio/n8n:${N8N_VERSION}amd64, arm64sha256:3cd1d3a03f5e059a0757d8c95823ff09ef61d3b6bf7fcb4ac3ac5fd5303b6c6dregistry-1.docker.io2026-10-01
n8n-runnern8nio/runners:${N8N_VERSION}amd64, arm64sha256:2797b628d7f87363b40a5b0d4d7e8a2ee960918d7f9ab9849fbb8be94f29ca16registry-1.docker.io2026-10-01
n8n-workerdocker.n8n.io/n8nio/n8n:${N8N_VERSION}amd64, arm64sha256:3cd1d3a03f5e059a0757d8c95823ff09ef61d3b6bf7fcb4ac3ac5fd5303b6c6dregistry-1.docker.io2026-10-01
n8n-worker-runnern8nio/runners:${N8N_VERSION}amd64, arm64sha256:2797b628d7f87363b40a5b0d4d7e8a2ee960918d7f9ab9849fbb8be94f29ca16registry-1.docker.io2026-10-01

A manifest says an image exists for a CPU, not how well n8n runs on it: a build for arm64 or arm/v7 can still be too slow or need more memory than the board has. The RAM and disk n8n publishes are in the table above and, for a whole set of apps against a Raspberry Pi, on Will it run on my machine?. A tag like latest can move to a new digest after the date checked.

docker-compose.yml

n8n keeps workflows, credentials and past executions in SQLite by default and also supports PostgreSQL, currently versions 16, 17 and 18. Its queue mode (separate worker containers) is not recommended on SQLite. Choose before the first start: to move an existing instance, n8n points to its export and import commands. Source: n8n docs: Supported databases and settings (DB_TYPE=postgresdb, supported PostgreSQL versions) checked 2026-09-30; n8n docs: Queue mode (database considerations, migrating data) checked 2026-09-30

Queue mode splits n8n in two: a main instance that serves the editor and receives triggers, timers and webhook calls, and workers that run the executions, handed over through Redis. n8n calls it the mode with the best scalability, and it needs PostgreSQL: n8n does not recommend queue mode on SQLite. Choose it before the first start, like PostgreSQL. Source: n8n docs: Enable queue mode (how it works, encryption key, Redis, workers, concurrency, binary data, multi-main) checked 2026-10-01

Every file and step below comes in each version, one after the other; with JavaScript on, the switch shows only the one you pick.

What queue mode changes

What this cannot do: it does not size workers for your workload (n8n publishes no figure for how many a given load needs), and it does not set up the separate webhook processors and load balancer n8n describes for scaling incoming webhooks.

With SQLite, the default

This is exactly what the builder writes for n8n alone on example.org: the official definition with its published ports removed and Caddy added in front. The time zone is Etc/UTC here; the builder uses your browser's.

# docker-compose.yml built at dankhost.com for: n8n
# Each app block is its official compose definition. Only the names were prefixed with
# the app slug (services, containers, volumes, bind folders, .env variables) so any set of
# apps can share one file; other differences are listed under "Changed:" in each block.
# Only Caddy publishes ports. Secrets live in .env next to this file.

services:
  # ---- Caddy: the one reverse proxy, HTTPS certificates from Let's Encrypt ----
  # Source: https://caddyserver.com/docs/running (checked 2026-09-23)
  # Source: https://github.com/dani-garcia/vaultwarden/wiki/Using-Docker-Compose (checked 2026-09-23)
  # Caddyfile goes in ./caddy/Caddyfile. Fixed address 172.30.0.2 so apps can trust it exactly.
  caddy:
    image: "caddy:2"
    container_name: "caddy"
    restart: "unless-stopped"
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - "./caddy:/etc/caddy"
      - "caddy-data:/data"
      - "caddy-config:/config"
    networks:
      proxy:
        ipv4_address: "172.30.0.2"

  # ---- n8n (n8n.example.org) ----
  # Source: https://docs.n8n.io/hosting/installation/server-setups/docker-compose/ (checked 2026-09-25)
  # Source: https://docs.n8n.io/hosting/configuration/environment-variables/deployment/ (checked 2026-09-25)
  # Changed: Removed the documented '127.0.0.1:5678:5678' port and the documented Traefik service and labels; Caddy reaches n8n:5678 on the proxy network.
  #          N8N_HOST, WEBHOOK_URL, GENERIC_TIMEZONE and TZ are filled in with your address and time zone instead of the documented .env variables SUBDOMAIN, DOMAIN_NAME and GENERIC_TIMEZONE.
  #          Added N8N_PROXY_HOPS=1 (deployment variables page: the number of reverse proxies n8n runs behind), since one proxy sits in front of it.
  #          The documented HSTS header middleware (STSSeconds 315360000 with includeSubdomains and preload) is left out: it would commit every subdomain of your domain to HTTPS-only for ten years. Add it yourself if that is what you want.
  n8n:
    image: "n8nio/n8n"
    container_name: "n8n"
    restart: "always"
    environment:
      N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS: "true"
      N8N_HOST: "n8n.example.org"
      N8N_PORT: "5678"
      N8N_PROTOCOL: "https"
      NODE_ENV: "production"
      WEBHOOK_URL: "https://n8n.example.org/"
      GENERIC_TIMEZONE: "Etc/UTC"
      TZ: "Etc/UTC"
      N8N_RESTRICT_FILE_ACCESS_TO: "/files"
      N8N_PROXY_HOPS: "1"
    volumes:
      - "n8n-n8n_data:/home/node/.n8n"
      - "./n8n/local-files:/files"
    networks:
      proxy: {}

networks:
  # Pinned so the trusted-proxy address given to each app (172.30.0.2) is exact.
  # If "docker compose up" reports "Pool overlaps", change 172.30.0 here, in Caddy's
  # ipv4_address and in every trusted-proxy value to a free 172.x.0 range.
  proxy:
    ipam:
      config:
        - subnet: "172.30.0.0/24"
          ip_range: "172.30.0.128/25"
          gateway: "172.30.0.1"

volumes:
  caddy-data:
  caddy-config:
  n8n-n8n_data:

With PostgreSQL

This is what the builder's code writes for n8n alone on example.org from the project's PostgreSQL setup (the builder on the front page still writes the SQLite version, so copy this one from here): the official definition with its published ports removed and Caddy added in front. The time zone is Etc/UTC here; the builder uses your browser's. Every ${VARIABLE} is defined in the .env below.

# docker-compose.yml built at dankhost.com for: n8n
# Each app block is its official compose definition. Only the names were prefixed with
# the app slug (services, containers, volumes, bind folders, .env variables) so any set of
# apps can share one file; other differences are listed under "Changed:" in each block.
# Only Caddy publishes ports. Secrets live in .env next to this file.

services:
  # ---- Caddy: the one reverse proxy, HTTPS certificates from Let's Encrypt ----
  # Source: https://caddyserver.com/docs/running (checked 2026-09-23)
  # Source: https://github.com/dani-garcia/vaultwarden/wiki/Using-Docker-Compose (checked 2026-09-23)
  # Caddyfile goes in ./caddy/Caddyfile. Fixed address 172.30.0.2 so apps can trust it exactly.
  caddy:
    image: "caddy:2"
    container_name: "caddy"
    restart: "unless-stopped"
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - "./caddy:/etc/caddy"
      - "caddy-data:/data"
      - "caddy-config:/config"
    networks:
      proxy:
        ipv4_address: "172.30.0.2"

  # ---- n8n (n8n.example.org) ----
  # Source: https://docs.n8n.io/hosting/installation/server-setups/docker-compose/ (checked 2026-09-25)
  # Source: https://docs.n8n.io/hosting/configuration/environment-variables/deployment/ (checked 2026-09-25)
  # Source: https://github.com/n8n-io/n8n-hosting/tree/main/docker-compose/withPostgres (checked 2026-09-30)
  # Source: https://docs.n8n.io/hosting/configuration/supported-databases-settings/ (checked 2026-09-30)
  # Source: https://docs.n8n.io/hosting/configuration/task-runners/ (checked 2026-09-30)
  # Source: https://hub.docker.com/_/postgres (checked 2026-09-30)
  # Changed: Removed the documented '127.0.0.1:5678:5678' port and the documented Traefik service and labels; Caddy reaches n8n:5678 on the proxy network.
  #          From n8n's withPostgres example: the postgres service (postgres:18, with PGDATA pinned to /var/lib/postgresql/data as the example does so the mount stays the same across major versions), its init-data.sh, which creates a separate non-superuser for n8n, the six DB_ variables on n8n, and n8n waiting for a healthy database.
  #          The example's healthcheck takes POSTGRES_USER and POSTGRES_DB from .env when compose starts; here it reads them inside the container ($$POSTGRES_USER, $$POSTGRES_DB), the same values, because this file's .env names carry the N8N_ prefix.
  #          The example's .env placeholders (changeUser, changePassword) become POSTGRES_USER=postgres, POSTGRES_NON_ROOT_USER=n8n and two generated passwords; POSTGRES_DB stays n8n.
  #          Left out: the example's n8n-runner service with its N8N_RUNNERS_ variables (external task runners, which run Code node code in their own container and have nothing to do with the database) and its legacy links: entry. Everything else about n8n (the n8nio/n8n image, the settings below, the n8n_data volume the example calls n8n_storage) is as in the SQLite version.
  #          N8N_HOST, WEBHOOK_URL, GENERIC_TIMEZONE and TZ are filled in with your address and time zone instead of the documented .env variables SUBDOMAIN, DOMAIN_NAME and GENERIC_TIMEZONE.
  #          Added N8N_PROXY_HOPS=1 (deployment variables page: the number of reverse proxies n8n runs behind), since one proxy sits in front of it.
  #          The documented HSTS header middleware (STSSeconds 315360000 with includeSubdomains and preload) is left out: it would commit every subdomain of your domain to HTTPS-only for ten years. Add it yourself if that is what you want.
  n8n-postgres:
    image: "postgres:18"
    container_name: "n8n-postgres"
    restart: "always"
    environment:
      POSTGRES_USER: "${N8N_POSTGRES_USER}"
      POSTGRES_PASSWORD: "${N8N_POSTGRES_PASSWORD}"
      POSTGRES_DB: "${N8N_POSTGRES_DB}"
      POSTGRES_NON_ROOT_USER: "${N8N_POSTGRES_NON_ROOT_USER}"
      POSTGRES_NON_ROOT_PASSWORD: "${N8N_POSTGRES_NON_ROOT_PASSWORD}"
      PGDATA: "/var/lib/postgresql/data"
    volumes:
      - "n8n-db_storage:/var/lib/postgresql/data"
      - "./n8n/init-data.sh:/docker-entrypoint-initdb.d/init-data.sh"
    healthcheck:
      test:
        - "CMD-SHELL"
        - "pg_isready -h localhost -U $$POSTGRES_USER -d $$POSTGRES_DB"
      interval: "5s"
      timeout: "5s"
      retries: 10
    networks:
      n8n-backend:
        aliases:
          - "postgres"
  n8n:
    image: "n8nio/n8n"
    container_name: "n8n"
    restart: "always"
    environment:
      N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS: "true"
      N8N_HOST: "n8n.example.org"
      N8N_PORT: "5678"
      N8N_PROTOCOL: "https"
      NODE_ENV: "production"
      WEBHOOK_URL: "https://n8n.example.org/"
      GENERIC_TIMEZONE: "Etc/UTC"
      TZ: "Etc/UTC"
      N8N_RESTRICT_FILE_ACCESS_TO: "/files"
      N8N_PROXY_HOPS: "1"
      DB_TYPE: "postgresdb"
      DB_POSTGRESDB_HOST: "postgres"
      DB_POSTGRESDB_PORT: "5432"
      DB_POSTGRESDB_DATABASE: "${N8N_POSTGRES_DB}"
      DB_POSTGRESDB_USER: "${N8N_POSTGRES_NON_ROOT_USER}"
      DB_POSTGRESDB_PASSWORD: "${N8N_POSTGRES_NON_ROOT_PASSWORD}"
    volumes:
      - "n8n-n8n_data:/home/node/.n8n"
      - "./n8n/local-files:/files"
    depends_on:
      n8n-postgres:
        condition: "service_healthy"
    networks:
      proxy: {}
      n8n-backend: {}

networks:
  # Pinned so the trusted-proxy address given to each app (172.30.0.2) is exact.
  # If "docker compose up" reports "Pool overlaps", change 172.30.0 here, in Caddy's
  # ipv4_address and in every trusted-proxy value to a free 172.x.0 range.
  proxy:
    ipam:
      config:
        - subnet: "172.30.0.0/24"
          ip_range: "172.30.0.128/25"
          gateway: "172.30.0.1"
  n8n-backend:
    internal: true

volumes:
  caddy-data:
  caddy-config:
  n8n-n8n_data:
  n8n-db_storage:

With PostgreSQL + workers (queue mode)

This is what the builder's code writes for n8n alone on example.org from the project's PostgreSQL + workers (queue mode) setup (the builder on the front page still writes the SQLite version, so copy this one from here): the official definition with its published ports removed and Caddy added in front. The time zone is Etc/UTC here; the builder uses your browser's. Every ${VARIABLE} is defined in the .env below.

# docker-compose.yml built at dankhost.com for: n8n
# Each app block is its official compose definition. Only the names were prefixed with
# the app slug (services, containers, volumes, bind folders, .env variables) so any set of
# apps can share one file; other differences are listed under "Changed:" in each block.
# Only Caddy publishes ports. Secrets live in .env next to this file.

services:
  # ---- Caddy: the one reverse proxy, HTTPS certificates from Let's Encrypt ----
  # Source: https://caddyserver.com/docs/running (checked 2026-09-23)
  # Source: https://github.com/dani-garcia/vaultwarden/wiki/Using-Docker-Compose (checked 2026-09-23)
  # Caddyfile goes in ./caddy/Caddyfile. Fixed address 172.30.0.2 so apps can trust it exactly.
  caddy:
    image: "caddy:2"
    container_name: "caddy"
    restart: "unless-stopped"
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - "./caddy:/etc/caddy"
      - "caddy-data:/data"
      - "caddy-config:/config"
    networks:
      proxy:
        ipv4_address: "172.30.0.2"

  # ---- n8n (n8n.example.org) ----
  # Source: https://github.com/n8n-io/n8n-hosting/tree/main/docker-compose/withPostgresAndWorker (checked 2026-10-01)
  # Source: https://docs.n8n.io/hosting/scaling/queue-mode/ (checked 2026-10-01)
  # Source: https://docs.n8n.io/hosting/configuration/task-runners/ (checked 2026-10-01)
  # Source: https://docs.n8n.io/administer/observe-and-log/stream-logs-to-external-systems#per-process-event-log-files (checked 2026-10-01)
  # Source: https://docs.n8n.io/hosting/installation/server-setups/docker-compose/ (checked 2026-09-25)
  # Source: https://docs.n8n.io/hosting/configuration/environment-variables/deployment/ (checked 2026-09-25)
  # Source: https://docs.n8n.io/hosting/configuration/supported-databases-settings/ (checked 2026-09-30)
  # Source: https://hub.docker.com/_/postgres (checked 2026-09-30)
  # Source: https://docs.docker.com/reference/compose-file/services/ (checked 2026-10-01)
  # Changed: Removed the published port '5678:5678' from n8n; Caddy reaches the main n8n at n8n:5678 on the proxy network. Only the main n8n is on that network: postgres, redis, the worker and both runners are on n8n's own network only.
  #          Expanded the YAML anchors x-shared and x-runner into each service, as YAML's merge key does: the worker's and the runners' own depends_on and environment replace the anchor's.
  #          No container_name on n8n-worker, so docker compose up -d --scale n8n-worker=N works; every other service gets its usual name.
  #          n8n's own network is an ordinary one, not internal: the worker runs the workflows, and their requests to other services have to reach the internet.
  #          Added to the main n8n only: N8N_HOST, N8N_PORT, N8N_PROTOCOL, NODE_ENV and WEBHOOK_URL with your address (from n8n's Docker Compose page), and N8N_PROXY_HOPS=1 (deployment variables page: the number of reverse proxies n8n runs behind), since one proxy sits in front of it.
  #          Added GENERIC_TIMEZONE and TZ (from n8n's Docker Compose page) to the main n8n and the worker, so both use the same time zone.
  #          The healthcheck takes POSTGRES_USER and POSTGRES_DB from .env when compose starts; here it reads them inside the container ($$POSTGRES_USER, $$POSTGRES_DB), the same values, because this file's .env names carry the N8N_ prefix. For the same reason postgres gets its five variables as ${...} instead of by name.
  #          The .env placeholders (changeUser, changePassword, changeEncryptionKey, changeRunnerAuthToken) become POSTGRES_USER=postgres, POSTGRES_NON_ROOT_USER=n8n and four blank secrets to fill; POSTGRES_DB stays n8n and N8N_VERSION stays 2.41.4, the value in n8n's .env.
  #          The volume n8n calls n8n_storage is n8n_data here, as in the SQLite and PostgreSQL versions; db_storage and redis_storage keep their names. There is no ./local-files folder, as in n8n's queue-mode file.
  n8n-postgres:
    image: "postgres:18"
    container_name: "n8n-postgres"
    restart: "always"
    environment:
      POSTGRES_USER: "${N8N_POSTGRES_USER}"
      POSTGRES_PASSWORD: "${N8N_POSTGRES_PASSWORD}"
      POSTGRES_DB: "${N8N_POSTGRES_DB}"
      POSTGRES_NON_ROOT_USER: "${N8N_POSTGRES_NON_ROOT_USER}"
      POSTGRES_NON_ROOT_PASSWORD: "${N8N_POSTGRES_NON_ROOT_PASSWORD}"
      PGDATA: "/var/lib/postgresql/data"
    volumes:
      - "n8n-db_storage:/var/lib/postgresql/data"
      - "./n8n/init-data.sh:/docker-entrypoint-initdb.d/init-data.sh"
    healthcheck:
      test:
        - "CMD-SHELL"
        - "pg_isready -h localhost -U $$POSTGRES_USER -d $$POSTGRES_DB"
      interval: "5s"
      timeout: "5s"
      retries: 10
    networks:
      n8n-backend:
        aliases:
          - "postgres"
  n8n-redis:
    image: "redis:7-alpine"
    container_name: "n8n-redis"
    restart: "always"
    volumes:
      - "n8n-redis_storage:/data"
    healthcheck:
      test:
        - "CMD"
        - "redis-cli"
        - "ping"
      interval: "5s"
      timeout: "5s"
      retries: 10
    networks:
      n8n-backend:
        aliases:
          - "redis"
  n8n:
    restart: "always"
    image: "docker.n8n.io/n8nio/n8n:${N8N_VERSION}"
    container_name: "n8n"
    environment:
      DB_TYPE: "postgresdb"
      DB_POSTGRESDB_HOST: "postgres"
      DB_POSTGRESDB_PORT: "5432"
      DB_POSTGRESDB_DATABASE: "${N8N_POSTGRES_DB}"
      DB_POSTGRESDB_USER: "${N8N_POSTGRES_NON_ROOT_USER}"
      DB_POSTGRESDB_PASSWORD: "${N8N_POSTGRES_NON_ROOT_PASSWORD}"
      EXECUTIONS_MODE: "queue"
      QUEUE_BULL_REDIS_HOST: "redis"
      QUEUE_HEALTH_CHECK_ACTIVE: "true"
      N8N_ENCRYPTION_KEY: "${N8N_ENCRYPTION_KEY}"
      N8N_RUNNERS_MODE: "external"
      N8N_RUNNERS_AUTH_TOKEN: "${N8N_RUNNERS_AUTH_TOKEN}"
      N8N_RUNNERS_BROKER_LISTEN_ADDRESS: "0.0.0.0"
      OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS: "true"
      N8N_HOST: "n8n.example.org"
      N8N_PORT: "5678"
      N8N_PROTOCOL: "https"
      NODE_ENV: "production"
      WEBHOOK_URL: "https://n8n.example.org/"
      GENERIC_TIMEZONE: "Etc/UTC"
      TZ: "Etc/UTC"
      N8N_PROXY_HOPS: "1"
    volumes:
      - "n8n-n8n_data:/home/node/.n8n"
    depends_on:
      n8n-redis:
        condition: "service_healthy"
      n8n-postgres:
        condition: "service_healthy"
    networks:
      proxy: {}
      n8n-backend: {}
  n8n-runner:
    restart: "always"
    image: "n8nio/runners:${N8N_VERSION}"
    container_name: "n8n-runner"
    environment:
      N8N_RUNNERS_AUTH_TOKEN: "${N8N_RUNNERS_AUTH_TOKEN}"
      N8N_RUNNERS_TASK_BROKER_URI: "http://n8n:5679"
    depends_on:
      - "n8n"
    networks:
      n8n-backend: {}
  n8n-worker:
    restart: "always"
    image: "docker.n8n.io/n8nio/n8n:${N8N_VERSION}"
    environment:
      DB_TYPE: "postgresdb"
      DB_POSTGRESDB_HOST: "postgres"
      DB_POSTGRESDB_PORT: "5432"
      DB_POSTGRESDB_DATABASE: "${N8N_POSTGRES_DB}"
      DB_POSTGRESDB_USER: "${N8N_POSTGRES_NON_ROOT_USER}"
      DB_POSTGRESDB_PASSWORD: "${N8N_POSTGRES_NON_ROOT_PASSWORD}"
      EXECUTIONS_MODE: "queue"
      QUEUE_BULL_REDIS_HOST: "redis"
      QUEUE_HEALTH_CHECK_ACTIVE: "true"
      N8N_ENCRYPTION_KEY: "${N8N_ENCRYPTION_KEY}"
      N8N_RUNNERS_MODE: "external"
      N8N_RUNNERS_AUTH_TOKEN: "${N8N_RUNNERS_AUTH_TOKEN}"
      N8N_RUNNERS_BROKER_LISTEN_ADDRESS: "0.0.0.0"
      OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS: "true"
      GENERIC_TIMEZONE: "Etc/UTC"
      TZ: "Etc/UTC"
    volumes:
      - "n8n-n8n_data:/home/node/.n8n"
    command: "worker"
    depends_on:
      - "n8n"
    networks:
      n8n-backend: {}
  n8n-worker-runner:
    restart: "always"
    image: "n8nio/runners:${N8N_VERSION}"
    container_name: "n8n-worker-runner"
    environment:
      N8N_RUNNERS_AUTH_TOKEN: "${N8N_RUNNERS_AUTH_TOKEN}"
      N8N_RUNNERS_TASK_BROKER_URI: "http://n8n-worker:5679"
    depends_on:
      - "n8n-worker"
    networks:
      n8n-backend: {}

networks:
  # Pinned so the trusted-proxy address given to each app (172.30.0.2) is exact.
  # If "docker compose up" reports "Pool overlaps", change 172.30.0 here, in Caddy's
  # ipv4_address and in every trusted-proxy value to a free 172.x.0 range.
  proxy:
    ipam:
      config:
        - subnet: "172.30.0.0/24"
          ip_range: "172.30.0.128/25"
          gateway: "172.30.0.1"
  n8n-backend: {}

volumes:
  caddy-data:
  caddy-config:
  n8n-n8n_data:
  n8n-db_storage:
  n8n-redis_storage:

Caddyfile save as caddy/Caddyfile

Caddy gets and renews the HTTPS certificate for n8n.example.org by itself once the DNS record points at your server and ports 80 and 443 reach it.

# Caddyfile built at dankhost.com. Save it as ./caddy/Caddyfile next to docker-compose.yml.
# Caddy gets and renews a Let's Encrypt certificate for each name below by itself,
# once the DNS records point at this server and ports 80 and 443 reach it.

# n8n
n8n.example.org {
	reverse_proxy n8n:5678
}

Already running nginx, Nginx Proxy Manager, Caddy or Traefik? The reverse-proxy settings n8n needs, for all four, each cited to n8n's own docs.

.env

With SQLite, the default

n8n needs no secret here; the builder adds nothing you have to fill in by hand.

# .env for n8n, from dankhost.com/app/n8n/. Nothing here is secret.
# Keep this file private (chmod 600).
# None of the chosen apps needs a variable here.

With PostgreSQL

The secrets are left blank here on purpose: a password printed on a public page is the same for everyone who copies it. Fill them with random letters and digits as in How to run it.

# .env for n8n, from dankhost.com/app/n8n/. Fill the blank secrets before starting.
# Keep this file private (chmod 600).

# n8n
N8N_POSTGRES_USER=postgres
# 32 random letters and digits, for example from: tr -dc A-Za-z0-9 </dev/urandom | head -c 32
N8N_POSTGRES_PASSWORD=
N8N_POSTGRES_DB=n8n
N8N_POSTGRES_NON_ROOT_USER=n8n
# 32 random letters and digits, for example from: tr -dc A-Za-z0-9 </dev/urandom | head -c 32
N8N_POSTGRES_NON_ROOT_PASSWORD=

With PostgreSQL + workers (queue mode)

The secrets are left blank here on purpose: a password printed on a public page is the same for everyone who copies it. Fill them with random letters and digits as in How to run it.

# .env for n8n, from dankhost.com/app/n8n/. Fill the blank secrets before starting.
# Keep this file private (chmod 600).

# n8n
# The n8n version for n8n, its worker and both runners (n8n's .env value); the runners image must match n8n's.
N8N_VERSION=2.41.4
N8N_POSTGRES_USER=postgres
# 32 random letters and digits, for example from: tr -dc A-Za-z0-9 </dev/urandom | head -c 32
N8N_POSTGRES_PASSWORD=
N8N_POSTGRES_DB=n8n
N8N_POSTGRES_NON_ROOT_USER=n8n
# 32 random letters and digits, for example from: tr -dc A-Za-z0-9 </dev/urandom | head -c 32
N8N_POSTGRES_NON_ROOT_PASSWORD=
# 32 random letters and digits, for example from: tr -dc A-Za-z0-9 </dev/urandom | head -c 32
N8N_ENCRYPTION_KEY=
# 32 random letters and digits, for example from: tr -dc A-Za-z0-9 </dev/urandom | head -c 32
N8N_RUNNERS_AUTH_TOKEN=

The file n8n needs next to the compose file

With SQLite, the default

n8n needs no file besides docker-compose.yml, .env and the Caddyfile.

With PostgreSQL

Copied from the project's own file. It holds no secret: it reads the passwords from the container's environment.

./n8n/init-data.sh

#!/bin/bash
set -e;


if [ -n "${POSTGRES_NON_ROOT_USER:-}" ] && [ -n "${POSTGRES_NON_ROOT_PASSWORD:-}" ]; then
	psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" <<-EOSQL
		CREATE USER ${POSTGRES_NON_ROOT_USER} WITH PASSWORD '${POSTGRES_NON_ROOT_PASSWORD}';
		GRANT ALL PRIVILEGES ON DATABASE ${POSTGRES_DB} TO ${POSTGRES_NON_ROOT_USER};
		GRANT CREATE ON SCHEMA public TO ${POSTGRES_NON_ROOT_USER};
	EOSQL
else
	echo "SETUP INFO: No Environment variables given!"
fi

With PostgreSQL + workers (queue mode)

Copied from the project's own file. It holds no secret: it reads the passwords from the container's environment.

./n8n/init-data.sh

#!/bin/bash
set -e;


if [ -n "${POSTGRES_NON_ROOT_USER:-}" ] && [ -n "${POSTGRES_NON_ROOT_PASSWORD:-}" ]; then
	psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" <<-EOSQL
		CREATE USER ${POSTGRES_NON_ROOT_USER} WITH PASSWORD '${POSTGRES_NON_ROOT_PASSWORD}';
		GRANT ALL PRIVILEGES ON DATABASE ${POSTGRES_DB} TO ${POSTGRES_NON_ROOT_USER};
		GRANT CREATE ON SCHEMA public TO ${POSTGRES_NON_ROOT_USER};
	EOSQL
else
	echo "SETUP INFO: No Environment variables given!"
fi

Changes from the official file

Besides prefixing every service, container, volume, folder and variable with n8n (so any set of apps can share one file), these are all the differences from what the project documents:

With SQLite, the default

  • Removed the documented '127.0.0.1:5678:5678' port and the documented Traefik service and labels; Caddy reaches n8n:5678 on the proxy network.
  • N8N_HOST, WEBHOOK_URL, GENERIC_TIMEZONE and TZ are filled in with your address and time zone instead of the documented .env variables SUBDOMAIN, DOMAIN_NAME and GENERIC_TIMEZONE.
  • Added N8N_PROXY_HOPS=1 (deployment variables page: the number of reverse proxies n8n runs behind), since one proxy sits in front of it.
  • The documented HSTS header middleware (STSSeconds 315360000 with includeSubdomains and preload) is left out: it would commit every subdomain of your domain to HTTPS-only for ten years. Add it yourself if that is what you want.

Notes for n8n behind the proxy

  • Open https://n8n.example.org and create the owner account straight away: until you do, whoever opens the address first can create it.
  • Create the folder for the Read/Write Files from Disk node before the first start, so it is owned by you rather than root: mkdir -p n8n/local-files. In n8n it is /files.
  • n8n generates its credentials encryption key on first start and keeps it in the n8n_data volume next to its SQLite database. Lose the volume and every saved credential is unreadable, so back it up (see BACKUP.md).

With PostgreSQL

  • Removed the documented '127.0.0.1:5678:5678' port and the documented Traefik service and labels; Caddy reaches n8n:5678 on the proxy network.
  • From n8n's withPostgres example: the postgres service (postgres:18, with PGDATA pinned to /var/lib/postgresql/data as the example does so the mount stays the same across major versions), its init-data.sh, which creates a separate non-superuser for n8n, the six DB_ variables on n8n, and n8n waiting for a healthy database.
  • The example's healthcheck takes POSTGRES_USER and POSTGRES_DB from .env when compose starts; here it reads them inside the container ($$POSTGRES_USER, $$POSTGRES_DB), the same values, because this file's .env names carry the N8N_ prefix.
  • The example's .env placeholders (changeUser, changePassword) become POSTGRES_USER=postgres, POSTGRES_NON_ROOT_USER=n8n and two generated passwords; POSTGRES_DB stays n8n.
  • Left out: the example's n8n-runner service with its N8N_RUNNERS_ variables (external task runners, which run Code node code in their own container and have nothing to do with the database) and its legacy links: entry. Everything else about n8n (the n8nio/n8n image, the settings below, the n8n_data volume the example calls n8n_storage) is as in the SQLite version.
  • N8N_HOST, WEBHOOK_URL, GENERIC_TIMEZONE and TZ are filled in with your address and time zone instead of the documented .env variables SUBDOMAIN, DOMAIN_NAME and GENERIC_TIMEZONE.
  • Added N8N_PROXY_HOPS=1 (deployment variables page: the number of reverse proxies n8n runs behind), since one proxy sits in front of it.
  • The documented HSTS header middleware (STSSeconds 315360000 with includeSubdomains and preload) is left out: it would commit every subdomain of your domain to HTTPS-only for ten years. Add it yourself if that is what you want.

Notes for n8n behind the proxy

  • Open https://n8n.example.org and create the owner account straight away: until you do, whoever opens the address first can create it.
  • Create the folder for the Read/Write Files from Disk node before the first start, so it is owned by you rather than root: mkdir -p n8n/local-files. In n8n it is /files.
  • Save init-data.sh from the files above as ./n8n/init-data.sh before the first start. PostgreSQL runs it only once, when it creates the database on an empty db_storage volume; if the file is missing then, Docker makes an empty folder of that name, the n8n user is never created and n8n cannot log in to the database.
  • n8n generates its credentials encryption key on first start and keeps it in the n8n_data volume. Workflows and credentials are in PostgreSQL, but without that key the credentials cannot be read, so back up both (see BACKUP.md).
  • Like the SQLite version, this file runs n8n's task runners inside the n8n container (internal mode). n8n's docs say internal mode is not recommended for production and is deprecated from n8n 3.0; their external mode is the n8n-runner service the example has.

With PostgreSQL + workers (queue mode)

  • Removed the published port '5678:5678' from n8n; Caddy reaches the main n8n at n8n:5678 on the proxy network. Only the main n8n is on that network: postgres, redis, the worker and both runners are on n8n's own network only.
  • Expanded the YAML anchors x-shared and x-runner into each service, as YAML's merge key does: the worker's and the runners' own depends_on and environment replace the anchor's.
  • No container_name on n8n-worker, so docker compose up -d --scale n8n-worker=N works; every other service gets its usual name.
  • n8n's own network is an ordinary one, not internal: the worker runs the workflows, and their requests to other services have to reach the internet.
  • Added to the main n8n only: N8N_HOST, N8N_PORT, N8N_PROTOCOL, NODE_ENV and WEBHOOK_URL with your address (from n8n's Docker Compose page), and N8N_PROXY_HOPS=1 (deployment variables page: the number of reverse proxies n8n runs behind), since one proxy sits in front of it.
  • Added GENERIC_TIMEZONE and TZ (from n8n's Docker Compose page) to the main n8n and the worker, so both use the same time zone.
  • The healthcheck takes POSTGRES_USER and POSTGRES_DB from .env when compose starts; here it reads them inside the container ($$POSTGRES_USER, $$POSTGRES_DB), the same values, because this file's .env names carry the N8N_ prefix. For the same reason postgres gets its five variables as ${...} instead of by name.
  • The .env placeholders (changeUser, changePassword, changeEncryptionKey, changeRunnerAuthToken) become POSTGRES_USER=postgres, POSTGRES_NON_ROOT_USER=n8n and four blank secrets to fill; POSTGRES_DB stays n8n and N8N_VERSION stays 2.41.4, the value in n8n's .env.
  • The volume n8n calls n8n_storage is n8n_data here, as in the SQLite and PostgreSQL versions; db_storage and redis_storage keep their names. There is no ./local-files folder, as in n8n's queue-mode file.

Notes for n8n behind the proxy

  • Open https://n8n.example.org and create the owner account straight away: until you do, whoever opens the address first can create it.
  • Save init-data.sh from the files above as ./n8n/init-data.sh before the first start. PostgreSQL runs it only once, when it creates the database on an empty db_storage volume; if the file is missing then, Docker makes an empty folder of that name, the n8n user is never created and n8n cannot log in to the database.
  • The encryption key is N8N_ENCRYPTION_KEY in .env, shared by the main n8n and the worker. Keep .env with your backups: n8n's README says that without that key the saved credentials cannot be decrypted, even with the database restored.
  • The task runners run Code node code in their own containers (external mode), which n8n's task-runner page recommends for production.

How to run it

With SQLite, the default

  1. At your DNS provider, add an A record named n8n on your domain pointing at the server's public IP address, and forward TCP 80, TCP 443 and UDP 443 to it.
  2. Save the three files in one folder: docker-compose.yml and .env side by side, the Caddyfile at ./caddy/Caddyfile. Replace example.org with your domain in the Caddyfile, the compose file and the .env, or let the builder do it.
  3. Nothing in .env needs filling in; chmod 600 .env all the same.
  4. Start it:
    docker compose up -d
    docker compose logs -f caddy   # watch the certificate arrive
  5. Open the new address (n8n. plus your domain) in a browser and follow the notes above.

With PostgreSQL

  1. At your DNS provider, add an A record named n8n on your domain pointing at the server's public IP address, and forward TCP 80, TCP 443 and UDP 443 to it.
  2. Save ./n8n/init-data.sh from the files above.
  3. Save the three files in one folder: docker-compose.yml and .env side by side, the Caddyfile at ./caddy/Caddyfile. Replace example.org with your domain in the Caddyfile, the compose file and the .env.
  4. Fill the blank N8N_POSTGRES_PASSWORD, N8N_POSTGRES_NON_ROOT_PASSWORD in .env. On the server, tr -dc A-Za-z0-9 </dev/urandom | head -c 32 prints 32 random letters and digits. Then chmod 600 .env.
  5. Start it:
    docker compose up -d
    docker compose logs -f caddy   # watch the certificate arrive
  6. Open the new address (n8n. plus your domain) in a browser and follow the notes above.

With PostgreSQL + workers (queue mode)

  1. At your DNS provider, add an A record named n8n on your domain pointing at the server's public IP address, and forward TCP 80, TCP 443 and UDP 443 to it.
  2. Save ./n8n/init-data.sh from the files above.
  3. Save the three files in one folder: docker-compose.yml and .env side by side, the Caddyfile at ./caddy/Caddyfile. Replace example.org with your domain in the Caddyfile, the compose file and the .env.
  4. Fill the blank N8N_POSTGRES_PASSWORD, N8N_POSTGRES_NON_ROOT_PASSWORD, N8N_ENCRYPTION_KEY, N8N_RUNNERS_AUTH_TOKEN in .env. On the server, tr -dc A-Za-z0-9 </dev/urandom | head -c 32 prints 32 random letters and digits. Then chmod 600 .env.
  5. Start it:
    docker compose up -d
    docker compose logs -f caddy   # watch the certificate arrive
  6. Open the new address (n8n. plus your domain) in a browser and follow the notes above.

Back it up

With SQLite, the default

n8n publishes no backup procedure for this setup. Its Docker Compose page says what the volumes hold: n8n_data is where n8n saves its SQLite database file and encryption key, and ./local-files is shared with the host. The copy below follows Docker's generic method with n8n stopped.

Below is the BACKUP.md the builder writes next to the compose file above: which of its folders and volumes hold data, what to copy with which container stopped, and a restore check. Pick more apps in the builder and it covers them all in one file.

# BACKUP.md built at dankhost.com for: n8n

What to copy from the docker-compose.yml built with this file, the database dump each project documents (rewritten for the service names in that file), what to copy with which container stopped, and how to check the result. Run every command in the folder that holds docker-compose.yml.

The folders are owned by the containers' users: put sudo in front of tar if it says "Permission denied". Named volumes live under /var/lib/docker/volumes, not next to the compose file, so they are copied through a throwaway ubuntu container (Docker's documented --volumes-from method). tar makes a full copy each run; for large folders an incremental tool (restic, borg, rsync) saves time and space.

Never run "docker compose down -v" on this file: it deletes the named volumes of every app in it.

## Before you start

    BACKUP=/mnt/backup/selfhost   # change this: a disk or machine other than this server's system disk
    mkdir -p "$BACKUP"

## Every time: the three stack files

    tar czf "$BACKUP/stack-files.tar.gz" docker-compose.yml .env caddy

.env holds the database passwords and secret keys the apps were set up with; keep this archive as private as the data.

## Caddy (the reverse proxy)

Caddy's docs: 'The data directory must not be treated as a cache.' It holds the TLS certificates and their private keys; without it Caddy has to ask Let's Encrypt for every certificate again.

- caddy-data (named volume, /data in caddy)
  BACK UP: TLS certificates, private keys, OCSP staples.
- caddy-config (named volume, /config in caddy)
  SKIP: the last active configuration, kept for 'caddy run --resume', which this setup does not use: it starts from the Caddyfile.
- ./caddy (/etc/caddy in caddy)
  IN stack-files.tar.gz: the Caddyfile, copied with the stack files above.

Copy (Caddy keeps serving while you copy):

    docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu tar cvf /backup/caddy-data.tar /data

Restore check:

    tar tf "$BACKUP/caddy-data.tar" > /dev/null && echo OK
    docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu bash -c "cd /data && tar xvf /backup/caddy-data.tar --strip 1"

Sources:
- Caddy docs: Conventions, Data directory: https://caddyserver.com/docs/conventions#data-directory (checked 2026-09-24)
- Docker docs: Volumes, Back up, restore, or migrate data volumes: https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes (checked 2026-09-24)

## n8n

n8n publishes no backup procedure for this setup. Its Docker Compose page says what the volumes hold: n8n_data is where n8n saves its SQLite database file and encryption key, and ./local-files is shared with the host. The copy below follows Docker's generic method with n8n stopped.

What this compose mounts:
- n8n-n8n_data (named volume, /home/node/.n8n in n8n)
  BACK UP: the SQLite database (workflows, credentials, execution history) and the encryption key that unlocks the credentials.
- ./n8n/local-files (/files in n8n)
  BACK UP: files your workflows read and write through /files.

1. Stop n8n. Stopping it keeps SQLite from writing mid-copy; a copy of a database file taken while it is being written can be unusable.

    docker compose stop n8n

2. Copy while n8n is stopped:

    docker run --rm --volumes-from n8n -v "$BACKUP":/backup ubuntu tar cvf /backup/n8n-n8n_data.tar /home/node/.n8n
    tar czf "$BACKUP/n8n-local-files.tar.gz" ./n8n/local-files

3. Start it again:

    docker compose start n8n

Restore check:

    tar tf "$BACKUP/n8n-n8n_data.tar" > /dev/null && echo OK
    tar tzf "$BACKUP/n8n-local-files.tar.gz" > /dev/null && echo OK

Put a copy back (with n8n stopped):

    docker run --rm --volumes-from n8n -v "$BACKUP":/backup ubuntu bash -c "cd /home/node/.n8n && tar xvf /backup/n8n-n8n_data.tar --strip 3"
    tar xzf "$BACKUP/n8n-local-files.tar.gz"   # recreates ./n8n/local-files; move the old folder aside first

Stop it, put the n8n_data volume and ./n8n/local-files back, start it. Restore the volume and the key together: credentials saved under one key cannot be read with another.

Sources:
- n8n docs: Use Docker Compose (compose.yaml, .env, volumes table): https://docs.n8n.io/hosting/installation/server-setups/docker-compose/ (checked 2026-09-25)
- Docker docs: Volumes, Back up, restore, or migrate data volumes: https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes (checked 2026-09-25)

With PostgreSQL

n8n publishes no backup procedure. Its withPostgres README dumps the database with pg_dumpall when upgrading PostgreSQL, and this plan uses the same command, plus a copy of n8n_data: the credentials in the database can only be read with the encryption key kept there.

Below is the BACKUP.md for the PostgreSQL version of the compose file above, written by the same code as the builder's: which of its folders and volumes hold data, the dump command the project documents, rewritten for this file's service names, what to copy with which container stopped, and a restore check.

# BACKUP.md built at dankhost.com for: n8n

What to copy from the docker-compose.yml built with this file, the database dump each project documents (rewritten for the service names in that file), what to copy with which container stopped, and how to check the result. Run every command in the folder that holds docker-compose.yml.

The folders are owned by the containers' users: put sudo in front of tar if it says "Permission denied". Named volumes live under /var/lib/docker/volumes, not next to the compose file, so they are copied through a throwaway ubuntu container (Docker's documented --volumes-from method). tar makes a full copy each run; for large folders an incremental tool (restic, borg, rsync) saves time and space.

Never run "docker compose down -v" on this file: it deletes the named volumes of every app in it.

## Before you start

    BACKUP=/mnt/backup/selfhost   # change this: a disk or machine other than this server's system disk
    mkdir -p "$BACKUP"

## Every time: the three stack files

    tar czf "$BACKUP/stack-files.tar.gz" docker-compose.yml .env caddy

.env holds the database passwords and secret keys the apps were set up with; keep this archive as private as the data.

## Caddy (the reverse proxy)

Caddy's docs: 'The data directory must not be treated as a cache.' It holds the TLS certificates and their private keys; without it Caddy has to ask Let's Encrypt for every certificate again.

- caddy-data (named volume, /data in caddy)
  BACK UP: TLS certificates, private keys, OCSP staples.
- caddy-config (named volume, /config in caddy)
  SKIP: the last active configuration, kept for 'caddy run --resume', which this setup does not use: it starts from the Caddyfile.
- ./caddy (/etc/caddy in caddy)
  IN stack-files.tar.gz: the Caddyfile, copied with the stack files above.

Copy (Caddy keeps serving while you copy):

    docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu tar cvf /backup/caddy-data.tar /data

Restore check:

    tar tf "$BACKUP/caddy-data.tar" > /dev/null && echo OK
    docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu bash -c "cd /data && tar xvf /backup/caddy-data.tar --strip 1"

Sources:
- Caddy docs: Conventions, Data directory: https://caddyserver.com/docs/conventions#data-directory (checked 2026-09-24)
- Docker docs: Volumes, Back up, restore, or migrate data volumes: https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes (checked 2026-09-24)

## n8n

n8n publishes no backup procedure. Its withPostgres README dumps the database with pg_dumpall when upgrading PostgreSQL, and this plan uses the same command, plus a copy of n8n_data: the credentials in the database can only be read with the encryption key kept there.

What this compose mounts:
- n8n-db_storage (named volume, /var/lib/postgresql/data in n8n-postgres)
  COVERED BY THE COMMAND BELOW: PostgreSQL's data files; the pg_dumpall below is the copy to keep.
- ./n8n/init-data.sh (/docker-entrypoint-initdb.d/init-data.sh in n8n-postgres)
  BACK UP: the script that creates the n8n database user on first start; the builder writes it again too.
- n8n-n8n_data (named volume, /home/node/.n8n in n8n)
  BACK UP: n8n's settings file with the encryption key that unlocks the credentials saved in the database.
- ./n8n/local-files (/files in n8n)
  BACK UP: files your workflows read and write through /files.

1. Stop n8n. With n8n stopped no workflow runs between the dump and the copy of n8n_data, so both come from the same moment. The database keeps running for the dump.

    docker compose stop n8n

2. Database dump for n8n-postgres:

    docker compose exec -T n8n-postgres sh -c 'pg_dumpall -U "$POSTGRES_USER"' > "$BACKUP/n8n-db.sql"

   The README's command, run inside the database container so the superuser name comes from its environment. pg_dumpall writes every database and both users.

3. Copy while n8n is stopped:

    tar czf "$BACKUP/n8n-init-data.sh.tar.gz" ./n8n/init-data.sh
    docker run --rm --volumes-from n8n -v "$BACKUP":/backup ubuntu tar cvf /backup/n8n-n8n_data.tar /home/node/.n8n
    tar czf "$BACKUP/n8n-local-files.tar.gz" ./n8n/local-files

4. Start it again:

    docker compose start n8n

Restore check:

    grep -c 'PostgreSQL database cluster dump complete' "$BACKUP/n8n-db.sql"   # 1 means pg_dumpall finished
    tar tzf "$BACKUP/n8n-init-data.sh.tar.gz" > /dev/null && echo OK
    tar tf "$BACKUP/n8n-n8n_data.tar" > /dev/null && echo OK
    tar tzf "$BACKUP/n8n-local-files.tar.gz" > /dev/null && echo OK

Put a copy back (with n8n stopped):

    tar xzf "$BACKUP/n8n-init-data.sh.tar.gz"   # recreates ./n8n/init-data.sh; move the old folder aside first
    docker run --rm --volumes-from n8n -v "$BACKUP":/backup ubuntu bash -c "cd /home/node/.n8n && tar xvf /backup/n8n-n8n_data.tar --strip 3"
    tar xzf "$BACKUP/n8n-local-files.tar.gz"   # recreates ./n8n/local-files; move the old folder aside first

Onto an empty db_storage volume: start only the database (init-data.sh creates the n8n user and database again), wait for it, load the dump, then start n8n. The README says to import before n8n starts, or n8n builds its own empty tables first and the import collides with them; errors that a role or database already exists are expected and your data still imports.

    docker compose up -d n8n-postgres
    until docker compose exec -T n8n-postgres pg_isready -h 127.0.0.1; do sleep 2; done   # waits until the first-start setup is over
    docker compose exec -T n8n-postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"' < "$BACKUP/n8n-db.sql"
    docker compose up -d

Put n8n_data back from the same backup: credentials saved under one encryption key cannot be read with another.

Sources:
- n8n-hosting: withPostgres README (PGDATA pin, upgrading PostgreSQL with pg_dumpall): https://github.com/n8n-io/n8n-hosting/blob/main/docker-compose/withPostgres/README.md (checked 2026-09-30)
- Docker docs: Volumes, Back up, restore, or migrate data volumes: https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes (checked 2026-09-25)

With PostgreSQL + workers (queue mode)

n8n publishes no backup procedure. Its withPostgresAndWorker README dumps the database with pg_dumpall when upgrading PostgreSQL, and this plan uses the same command, plus a copy of n8n_data and of .env: in this version the encryption key is N8N_ENCRYPTION_KEY in .env, and the README warns that without it the saved credentials cannot be decrypted, even with the database restored.

Below is the BACKUP.md for the PostgreSQL + workers (queue mode) version of the compose file above, written by the same code as the builder's: which of its folders and volumes hold data, the dump command the project documents, rewritten for this file's service names, what to copy with which container stopped, and a restore check.

# BACKUP.md built at dankhost.com for: n8n

What to copy from the docker-compose.yml built with this file, the database dump each project documents (rewritten for the service names in that file), what to copy with which container stopped, and how to check the result. Run every command in the folder that holds docker-compose.yml.

The folders are owned by the containers' users: put sudo in front of tar if it says "Permission denied". Named volumes live under /var/lib/docker/volumes, not next to the compose file, so they are copied through a throwaway ubuntu container (Docker's documented --volumes-from method). tar makes a full copy each run; for large folders an incremental tool (restic, borg, rsync) saves time and space.

Never run "docker compose down -v" on this file: it deletes the named volumes of every app in it.

## Before you start

    BACKUP=/mnt/backup/selfhost   # change this: a disk or machine other than this server's system disk
    mkdir -p "$BACKUP"

## Every time: the three stack files

    tar czf "$BACKUP/stack-files.tar.gz" docker-compose.yml .env caddy

.env holds the database passwords and secret keys the apps were set up with; keep this archive as private as the data.

## Caddy (the reverse proxy)

Caddy's docs: 'The data directory must not be treated as a cache.' It holds the TLS certificates and their private keys; without it Caddy has to ask Let's Encrypt for every certificate again.

- caddy-data (named volume, /data in caddy)
  BACK UP: TLS certificates, private keys, OCSP staples.
- caddy-config (named volume, /config in caddy)
  SKIP: the last active configuration, kept for 'caddy run --resume', which this setup does not use: it starts from the Caddyfile.
- ./caddy (/etc/caddy in caddy)
  IN stack-files.tar.gz: the Caddyfile, copied with the stack files above.

Copy (Caddy keeps serving while you copy):

    docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu tar cvf /backup/caddy-data.tar /data

Restore check:

    tar tf "$BACKUP/caddy-data.tar" > /dev/null && echo OK
    docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu bash -c "cd /data && tar xvf /backup/caddy-data.tar --strip 1"

Sources:
- Caddy docs: Conventions, Data directory: https://caddyserver.com/docs/conventions#data-directory (checked 2026-09-24)
- Docker docs: Volumes, Back up, restore, or migrate data volumes: https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes (checked 2026-09-24)

## n8n

n8n publishes no backup procedure. Its withPostgresAndWorker README dumps the database with pg_dumpall when upgrading PostgreSQL, and this plan uses the same command, plus a copy of n8n_data and of .env: in this version the encryption key is N8N_ENCRYPTION_KEY in .env, and the README warns that without it the saved credentials cannot be decrypted, even with the database restored.

What this compose mounts:
- n8n-db_storage (named volume, /var/lib/postgresql/data in n8n-postgres)
  COVERED BY THE COMMAND BELOW: PostgreSQL's data files; the pg_dumpall below is the copy to keep.
- ./n8n/init-data.sh (/docker-entrypoint-initdb.d/init-data.sh in n8n-postgres)
  BACK UP: the script that creates the n8n database user on first start; the page gives it again too.
- n8n-redis_storage (named volume, /data in n8n-redis)
  SKIP: Redis's data: the queue of executions waiting for a worker. n8n's queue-mode page calls Redis the message broker and the database the place data persists, and publishes no rule on backing Redis up.
- n8n-n8n_data (named volume, /home/node/.n8n in n8n)
  BACK UP: n8n's user folder (/home/node/.n8n), which n8n's file mounts in the main instance and the worker alike.
- n8n-n8n_data (named volume, /home/node/.n8n in n8n-worker)
  BACK UP: n8n's user folder (/home/node/.n8n), which n8n's file mounts in the main instance and the worker alike.

1. Stop n8n, n8n-worker. With the main n8n and the worker stopped, no workflow runs between the dump and the copy of n8n_data, so both come from the same moment. The database keeps running for the dump.

    docker compose stop n8n n8n-worker

2. Database dump for n8n-postgres:

    docker compose exec -T n8n-postgres sh -c 'pg_dumpall -U "$POSTGRES_USER"' > "$BACKUP/n8n-db.sql"

   The README's command, run inside the database container so the superuser name comes from its environment. pg_dumpall writes every database and both users.

3. Copy while n8n, n8n-worker are stopped:

    tar czf "$BACKUP/n8n-init-data.sh.tar.gz" ./n8n/init-data.sh
    docker run --rm --volumes-from n8n -v "$BACKUP":/backup ubuntu tar cvf /backup/n8n-n8n_data.tar /home/node/.n8n
    docker run --rm --volumes-from n8n-worker -v "$BACKUP":/backup ubuntu tar cvf /backup/n8n-n8n_data.tar /home/node/.n8n

4. Start it again:

    docker compose start n8n n8n-worker

Restore check:

    grep -c 'PostgreSQL database cluster dump complete' "$BACKUP/n8n-db.sql"   # 1 means pg_dumpall finished
    tar tzf "$BACKUP/n8n-init-data.sh.tar.gz" > /dev/null && echo OK
    tar tf "$BACKUP/n8n-n8n_data.tar" > /dev/null && echo OK
    tar tf "$BACKUP/n8n-n8n_data.tar" > /dev/null && echo OK

Put a copy back (with n8n, n8n-worker stopped):

    tar xzf "$BACKUP/n8n-init-data.sh.tar.gz"   # recreates ./n8n/init-data.sh; move the old folder aside first
    docker run --rm --volumes-from n8n -v "$BACKUP":/backup ubuntu bash -c "cd /home/node/.n8n && tar xvf /backup/n8n-n8n_data.tar --strip 3"
    docker run --rm --volumes-from n8n-worker -v "$BACKUP":/backup ubuntu bash -c "cd /home/node/.n8n && tar xvf /backup/n8n-n8n_data.tar --strip 3"

Onto an empty db_storage volume: start only the database (init-data.sh creates the n8n user and database again), wait for it, load the dump, then start the rest. The README says to import before n8n starts, or n8n builds its own empty tables first and the import collides with them; errors that a role or database already exists are expected and your data still imports.

    docker compose up -d n8n-postgres
    until docker compose exec -T n8n-postgres pg_isready -h 127.0.0.1; do sleep 2; done   # waits until the first-start setup is over
    docker compose exec -T n8n-postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"' < "$BACKUP/n8n-db.sql"
    docker compose up -d

Put .env (with N8N_ENCRYPTION_KEY) and n8n_data back from the same backup: credentials saved under one encryption key cannot be read with another.

Sources:
- n8n-hosting: withPostgresAndWorker README (encryption key in .env, upgrading PostgreSQL with pg_dumpall): https://github.com/n8n-io/n8n-hosting/blob/main/docker-compose/withPostgresAndWorker/README.md (checked 2026-10-01)
- n8n docs: Enable queue mode (how it works, encryption key, Redis, workers, concurrency, binary data, multi-main): https://docs.n8n.io/hosting/scaling/queue-mode/ (checked 2026-10-01)
- Docker docs: Volumes, Back up, restore, or migrate data volumes: https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes (checked 2026-09-25)

Update it

With SQLite, the default

What docker compose pull does depends only on how each image line in the compose file above is tagged. For n8n as this page writes it:

ServiceImageHow it is pinnedWhat docker compose pull does
caddycaddy:2Major version only (tag 2)Takes the newest image tagged 2: minor and patch releases of 2, never 3. A new major version needs a tag edit.
n8nn8nio/n8nNot pinned: no tag, which means latestMoves to the newest image published as latest, which can be a new major version.

What n8n's docs say about updating

n8n's own advice for self-hosters: update often, at least once a month, so you never have to jump several versions at once, and read the release notes for breaking changes before each update. For Docker Compose its docs give the pull-and-recreate commands below.

  • The image here has no tag, which means latest: docker compose pull takes the newest stable n8n, and that includes a new major version. n8n's Docker page shows pulling a specific version instead (its example is n8nio/n8n:1.81.0); write a version in the image tag to decide yourself when the next one arrives.
  • n8n publishes a separate list of breaking changes for each major version (2.0, and one for the coming 3.0) besides the release notes.
  • n8n suggests testing an update on a separate test instance first, using its Environments feature.
  • n8n's Compose steps run docker compose down between pull and up; docker compose up -d on its own also replaces every container whose image changed.

Source: n8n docs: Update n8n (best practices) checked 2026-09-30; n8n docs: Install with Docker, Updating Docker Compose checked 2026-09-30; n8n docs: Release notes checked 2026-09-30

The steps

  1. Back up first, as in Back it up above. An update can migrate n8n's data on its first start; the copy is the way back.
  2. Download the new images. Running containers are not touched yet:
    docker compose pull
  3. Recreate the containers whose image changed. Volumes and bind-mounted folders stay as they are:
    docker compose up -d
  4. Watch n8n start (Ctrl+C stops following the log, not the app):
    docker compose logs -f n8n
  5. Optional: remove the old images the pull left without a tag. This covers every stack on the machine, not only this one:
    docker image prune

Docker's reference for these commands: Docker docs: docker compose pull checked 2026-09-30; Docker docs: docker compose up (recreates changed containers, keeps volumes) checked 2026-09-30; Docker docs: docker image prune checked 2026-09-30

With PostgreSQL

What docker compose pull does depends only on how each image line in the compose file above is tagged. For n8n as this page writes it:

ServiceImageHow it is pinnedWhat docker compose pull does
caddycaddy:2Major version only (tag 2)Takes the newest image tagged 2: minor and patch releases of 2, never 3. A new major version needs a tag edit.
n8n-postgres databasepostgres:18Major version only (tag 18)Takes the newest image tagged 18: minor and patch releases of 18, never 19. A new major version needs a tag edit.
n8nn8nio/n8nNot pinned: no tag, which means latestMoves to the newest image published as latest, which can be a new major version.

Do not raise the major version of n8n-postgres by editing its tag. Keep its tag, 18, as it is when you update n8n.

PostgreSQL's docs: a new major version may change how data is stored on disk, so a data folder written by an older major version will not start under a newer one (the server refuses it). Moving needs a dump and restore (pg_dumpall, then load the dump into the new version) or pg_upgrade. Minor releases of the same major version never change the storage format. Source: PostgreSQL docs: Upgrading a PostgreSQL Cluster checked 2026-09-30

What n8n's docs say about updating

n8n's own advice for self-hosters: update often, at least once a month, so you never have to jump several versions at once, and read the release notes for breaking changes before each update. For Docker Compose its docs give the pull-and-recreate commands below.

  • The image here has no tag, which means latest: docker compose pull takes the newest stable n8n, and that includes a new major version. n8n's Docker page shows pulling a specific version instead (its example is n8nio/n8n:1.81.0); write a version in the image tag to decide yourself when the next one arrives.
  • n8n publishes a separate list of breaking changes for each major version (2.0, and one for the coming 3.0) besides the release notes.
  • n8n suggests testing an update on a separate test instance first, using its Environments feature.
  • n8n's Compose steps run docker compose down between pull and up; docker compose up -d on its own also replaces every container whose image changed.
  • n8n and PostgreSQL are updated separately, one tag at a time. The postgres tag, 18, takes every 18.x release on docker compose pull; PostgreSQL says minor releases never change the storage format, so that is safe. n8n supports PostgreSQL 16, 17 and 18 (as of July 2026).
  • A new PostgreSQL major version cannot read the data of the old one: n8n's README says bumping 16 to 18 stops with 'FATAL: database files are incompatible with server', and points to PostgreSQL's Upgrading a PostgreSQL Cluster page, where the simple method is a dump and restore. Its steps, with this file's names: stop n8n, dump, check the dump, remove only the database volume, edit the tag, start the database alone, load the dump, start the rest:
    docker compose stop n8n
    docker compose exec -T n8n-postgres sh -c 'pg_dumpall -U "$POSTGRES_USER"' > n8n-pg18.sql
    grep -c 'PostgreSQL database cluster dump complete' n8n-pg18.sql   # must print 1 before you go on
    docker compose rm -sf n8n-postgres
    docker volume ls --filter name=n8n-db_storage   # its full name starts with your project name; then: docker volume rm <that name>
    docker compose up -d n8n-postgres   # after editing the tag
    until docker compose exec -T n8n-postgres pg_isready -h 127.0.0.1; do sleep 2; done   # waits until the first-start setup is over
    docker compose exec -T n8n-postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"' < n8n-pg18.sql
    docker compose up -d
  • The README warns never to use docker compose down -v here: it deletes n8n_data too, and with it the encryption key.

Source: n8n docs: Update n8n (best practices) checked 2026-09-30; n8n docs: Install with Docker, Updating Docker Compose checked 2026-09-30; n8n docs: Release notes checked 2026-09-30; n8n-hosting: withPostgres README (PGDATA pin, upgrading PostgreSQL with pg_dumpall) checked 2026-09-30; n8n docs: Supported databases and settings (DB_TYPE=postgresdb, supported PostgreSQL versions) checked 2026-09-30; PostgreSQL docs: Upgrading a PostgreSQL Cluster checked 2026-09-30

The steps

  1. Back up first, as in Back it up above. An update can migrate n8n's data on its first start and its database with it; the copy is the way back.
  2. Download the new images. Running containers are not touched yet:
    docker compose pull
  3. Recreate the containers whose image changed. Volumes and bind-mounted folders stay as they are:
    docker compose up -d
  4. Watch n8n start (Ctrl+C stops following the log, not the app):
    docker compose logs -f n8n
  5. Optional: remove the old images the pull left without a tag. This covers every stack on the machine, not only this one:
    docker image prune

Docker's reference for these commands: Docker docs: docker compose pull checked 2026-09-30; Docker docs: docker compose up (recreates changed containers, keeps volumes) checked 2026-09-30; Docker docs: docker image prune checked 2026-09-30

With PostgreSQL + workers (queue mode)

What docker compose pull does depends only on how each image line in the compose file above is tagged. For n8n as this page writes it:

ServiceImageHow it is pinnedWhat docker compose pull does
caddycaddy:2Major version only (tag 2)Takes the newest image tagged 2: minor and patch releases of 2, never 3. A new major version needs a tag edit.
n8n-postgres databasepostgres:18Major version only (tag 18)Takes the newest image tagged 18: minor and patch releases of 18, never 19. A new major version needs a tag edit.
n8n-redisredis:7-alpineMajor version only (tag 7-alpine)Takes the newest image tagged 7-alpine: minor and patch releases of 7, never 8. A new major version needs a tag edit.
n8ndocker.n8n.io/n8nio/n8n:${N8N_VERSION}Exact version (tag 2.41.4) (.env sets N8N_VERSION=2.41.4)Does not move: stays on 2.41.4 until you edit the tag (a publisher may re-push the same version on a rebuilt base).
n8n-runnern8nio/runners:${N8N_VERSION}Exact version (tag 2.41.4) (.env sets N8N_VERSION=2.41.4)Does not move: stays on 2.41.4 until you edit the tag (a publisher may re-push the same version on a rebuilt base).
n8n-workerdocker.n8n.io/n8nio/n8n:${N8N_VERSION}Exact version (tag 2.41.4) (.env sets N8N_VERSION=2.41.4)Does not move: stays on 2.41.4 until you edit the tag (a publisher may re-push the same version on a rebuilt base).
n8n-worker-runnern8nio/runners:${N8N_VERSION}Exact version (tag 2.41.4) (.env sets N8N_VERSION=2.41.4)Does not move: stays on 2.41.4 until you edit the tag (a publisher may re-push the same version on a rebuilt base).

Do not raise the major version of n8n-postgres by editing its tag. Keep its tag, 18, as it is when you update n8n.

PostgreSQL's docs: a new major version may change how data is stored on disk, so a data folder written by an older major version will not start under a newer one (the server refuses it). Moving needs a dump and restore (pg_dumpall, then load the dump into the new version) or pg_upgrade. Minor releases of the same major version never change the storage format. Source: PostgreSQL docs: Upgrading a PostgreSQL Cluster checked 2026-09-30

What n8n's docs say about updating

n8n's own advice for self-hosters: update often, at least once a month, so you never have to jump several versions at once, and read the release notes for breaking changes before each update. Here the n8n version is the N8N_VERSION line in .env, not the image tag.

  • To update n8n: change N8N_VERSION in .env to the new version, then docker compose pull and docker compose up -d. The main n8n, the worker and both runners move together; n8n's task-runner page says the runners image version must match n8n's.
    docker compose pull
    docker compose up -d
  • n8n publishes a separate list of breaking changes for each major version (2.0, and one for the coming 3.0) besides the release notes.
  • n8n suggests testing an update on a separate test instance first, using its Environments feature.
  • Redis's tag, 7-alpine, takes every 7.x release on docker compose pull. n8n publishes no rule on which Redis versions it supports.
  • n8n and PostgreSQL are updated separately, one tag at a time. The postgres tag, 18, takes every 18.x release on docker compose pull; PostgreSQL says minor releases never change the storage format, so that is safe. n8n supports PostgreSQL 16, 17 and 18 (as of July 2026).
  • A new PostgreSQL major version cannot read the data of the old one: n8n's README says bumping 16 to 18 stops with 'FATAL: database files are incompatible with server', and points to PostgreSQL's Upgrading a PostgreSQL Cluster page, where the simple method is a dump and restore. Its steps, with this file's names: stop n8n and the worker, dump, check the dump, remove only the database volume, edit the tag, start the database alone, load the dump, start the rest:
    docker compose stop n8n n8n-worker
    docker compose exec -T n8n-postgres sh -c 'pg_dumpall -U "$POSTGRES_USER"' > n8n-pg-dump.sql
    grep -c 'PostgreSQL database cluster dump complete' n8n-pg-dump.sql   # must print 1 before you go on
    docker compose rm -sf n8n-postgres
    docker volume ls --filter name=n8n-db_storage   # its full name starts with your project name; then: docker volume rm <that name>
    docker compose up -d n8n-postgres   # after editing the tag
    until docker compose exec -T n8n-postgres pg_isready -h 127.0.0.1; do sleep 2; done   # waits until the first-start setup is over
    docker compose exec -T n8n-postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"' < n8n-pg-dump.sql
    docker compose up -d
  • The README warns never to use docker compose down -v here: it deletes n8n_data too.

Source: n8n docs: Update n8n (best practices) checked 2026-09-30; n8n docs: Install with Docker, Updating Docker Compose checked 2026-09-30; n8n docs: Release notes checked 2026-09-30; n8n-hosting: withPostgresAndWorker README (encryption key in .env, upgrading PostgreSQL with pg_dumpall) checked 2026-10-01; n8n docs: Set up task runners (external mode, one sidecar per worker, runners version must match n8n) checked 2026-10-01; n8n docs: Supported databases and settings (DB_TYPE=postgresdb, supported PostgreSQL versions) checked 2026-09-30; PostgreSQL docs: Upgrading a PostgreSQL Cluster checked 2026-09-30

The steps

  1. Back up first, as in Back it up above. An update can migrate n8n's data on its first start and its database with it; the copy is the way back.
  2. n8n and n8n-worker are pinned to an exact version (see the table), so a pull alone changes nothing there: to update n8n, first edit their tags in docker-compose.yml to the version you want.
  3. Download the new images. Running containers are not touched yet:
    docker compose pull
  4. Recreate the containers whose image changed. Volumes and bind-mounted folders stay as they are:
    docker compose up -d
  5. Watch n8n start (Ctrl+C stops following the log, not the app):
    docker compose logs -f n8n
  6. Optional: remove the old images the pull left without a tag. This covers every stack on the machine, not only this one:
    docker image prune

Docker's reference for these commands: Docker docs: docker compose pull checked 2026-09-30; Docker docs: docker compose up (recreates changed containers, keeps volumes) checked 2026-09-30; Docker docs: docker image prune checked 2026-09-30

Locked out? Reset the admin password

Not a password reset: n8n's documented way back in returns user management to its pre-setup state and removes all user accounts, so you set up the owner account again. n8n's docs give it for a forgotten password when no SMTP is set up for reset emails.

Run the n8n CLI as the node user in the container. Source: n8n docs: CLI commands, User management read 2026-10-03

docker compose exec -u node n8n n8n user-management:reset

Run the commands in the folder that holds docker-compose.yml. docker compose exec runs the command in the container that is already running: Docker docs: docker compose exec read 2026-10-03

Sources

Every page below was fetched on the date shown.

Add n8n to the builder All one hundred apps

Made with AI tools. ยท Privacy