Tutorial cover

Deploy n8n with Docker Compose and PostgreSQL

n8n needs two services: n8n itself and PostgreSQL for workflows and credentials. Below is a compose file we started on a server, the variables it needs, how much memory it really uses, and the error you get when the memory limit is too low.

docker-compose.yml

services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
      POSTGRES_DB: n8n
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U n8n -d n8n"]
      interval: 5s
      timeout: 3s
      retries: 10
    mem_limit: 256m
    restart: unless-stopped

  n8n:
    image: docker.n8n.io/n8nio/n8n:2.48.4
    environment:
      DB_TYPE: postgresdb
      DB_POSTGRESDB_HOST: postgres
      DB_POSTGRESDB_DATABASE: n8n
      DB_POSTGRESDB_USER: n8n
      DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}
      N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY:?set N8N_ENCRYPTION_KEY}
      N8N_HOST: ${N8N_HOST}
      N8N_PROTOCOL: https
      N8N_WEBHOOK_URL: https://${N8N_HOST}/
      GENERIC_TIMEZONE: Europe/Oslo
    ports:
      - "5678:5678"
    volumes:
      - n8n-data:/home/node/.n8n
    mem_limit: 768m
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

volumes:
  db-data:
  n8n-data:
  • depends_on with service_healthy keeps n8n from starting before PostgreSQL accepts connections.
  • ${VAR:?message} stops docker compose up with that message if the variable is not set, instead of starting with an empty password.
  • Pin the image version (2.48.4 here) and update it on purpose: a new n8n version migrates the database on start.

Variables

Put them in .env next to the compose file:

POSTGRES_PASSWORD=$(openssl rand -hex 16)
N8N_ENCRYPTION_KEY=$(openssl rand -hex 32)
cat > .env <<EOF
POSTGRES_PASSWORD=$POSTGRES_PASSWORD
N8N_ENCRYPTION_KEY=$N8N_ENCRYPTION_KEY
N8N_HOST=n8n.example.com
EOF

N8N_ENCRYPTION_KEY encrypts the credentials stored in the database. Save it with your backups: without it, a restored database has credentials nobody can read.

N8N_HOST and N8N_WEBHOOK_URL must be the public address. n8n shows webhook URLs built from them; with the defaults you get http://localhost:5678/webhook/..., which external services cannot call.

Start and check

docker compose up -d
curl localhost:5678/healthz
 Container n8n-postgres-1 Healthy
 Container n8n-n8n-1 Starting
 Container n8n-n8n-1 Started
{"status":"ok"}

$ docker compose ps
SERVICE    STATUS                    PORTS
n8n        Up 14 seconds             0.0.0.0:5678->5678/tcp
postgres   Up 20 seconds (healthy)   5432/tcp

/healthz answered after about 15 seconds. Open http://<server>:5678 and create the owner account: the first person who opens the page becomes the owner, so do it right away.

How much memory

Measured with docker stats on an idle instance:

Service Memory
n8n 2.48.4 ~370 MiB
PostgreSQL 17 ~30–40 MiB

Plan for at least 1 GB of RAM for the pair, more if your workflows process big files.

Error: JavaScript heap out of memory

With a 512 MB limit n8n does not start. The container restarts every ~40 seconds with exit code 134, and the log ends with:

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

docker stats at that moment shows only ~185 MiB used: Node.js sizes its heap from the container limit, so it fails long before the limit itself is reached. OOMKilled is false, which makes the cause easy to miss. Raise the limit to 768 MB (mem_limit: 768m above) and the same instance starts and stays at ~370 MiB.

HTTPS

Do not leave port 5678 open to the internet: n8n sends the login and session cookies over it in plain text. Put a reverse proxy with a TLS certificate in front of it, point the DNS record of N8N_HOST to the server and open only ports 80 and 443.

Backups

Everything is in two volumes: db-data (workflows, executions, credentials) and n8n-data (settings and the key file). A consistent database dump:

docker compose exec -T postgres pg_dump -U n8n n8n > n8n-$(date +%F).sql

Keep the dump together with N8N_ENCRYPTION_KEY.

The same in one click

On Jambotron you upload this compose file (or connect a Git repository), set POSTGRES_PASSWORD, N8N_ENCRYPTION_KEY and N8N_HOST in the project variables and press Deploy. Then add a domain for the n8n service with container port 5678: it works over HTTPS at once, the certificate is issued automatically, and port 5678 is never open to the internet. mem_limit from the file is applied within the memory of your plan.

See also

Back to list