This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.
What n8n does and what it needs
n8n is a fair-code workflow automation platform with a visual canvas, 1500+ integrations, and native AI agent support. You build workflows by wiring nodes together, drop into JavaScript or Python when the visual editor runs out, and schedule or trigger runs via webhooks, cron, or app events. Self-hosting gives you full control over credentials, execution data, and outbound network access — useful when workflows touch internal systems or sensitive data.
The official Docker Compose example runs a single n8nio/n8n container backed by a named volume for the SQLite database and encryption key. That is the simplest production shape and what this guide uses. The upstream project does not publish a minimum memory figure. Practical sizing depends on workload: an idle instance with a handful of scheduled workflows is light, while heavy AI nodes, large file transfers, and high-frequency webhooks push both RAM and CPU. Watch container memory during the first week and scale the VPS if you see sustained pressure.
Prerequisites, ports, and volume constraints
- A Linux server with Docker Engine and the Compose plugin (
docker --version,docker compose version). - A DNS A record for the subdomain you will use (for example
n8n.example.com) pointing at the server IP. - Port
5678is the n8n HTTP port. In this setup it binds to127.0.0.1:5678only, so a reverse proxy on the same host terminates TLS. - One named volume,
n8n_data, mounted at/home/node/.n8n. It holds the SQLite database and the encryption key that protects stored credentials. Lose it and you lose every saved credential. - An optional bind mount for file nodes. Create
./local-fileson the host and mount it at/files; setN8N_RESTRICT_FILE_ACCESS_TO=/filesso the Read/Write Files node cannot wander outside that directory.
If you are testing without a domain, either SSH-tunnel to the loopback port (ssh -L 5678:127.0.0.1:5678 user@server) or temporarily change the port mapping to 5678:5678 and open the firewall for your IP only. Do not leave it publicly exposed without TLS.
Production Docker Compose setup
Create the project directory and the file-share directory first:
mkdir -p ~/n8n-compose/local-files cd ~/n8n-compose Write the Compose file. It runs only n8n; the reverse proxy lives outside this stack so the app boots standalone.
cat <<'EOF' > compose.yml services: n8n: image: docker.n8n.io/n8nio/n8n:${N8N_VERSION:-stable} restart: unless-stopped ports: - "127.0.0.1:5678:5678" environment: - N8N_HOST=${N8N_HOST} - N8N_PORT=5678 - N8N_PROTOCOL=https - NODE_ENV=production - N8N_WEBHOOK_URL=https://${N8N_HOST}/ - GENERIC_TIMEZONE=${GENERIC_TIMEZONE:-UTC} - TZ=${GENERIC_TIMEZONE:-UTC} - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true - N8N_RESTRICT_FILE_ACCESS_TO=/files volumes: - n8n_data:/home/node/.n8n - ./local-files:/files volumes: n8n_data: EOF Now the .env. Generate a strong encryption key with openssl rand -hex 32 and paste it into N8N_ENCRYPTION_KEY. Keep that value somewhere safe — if you ever recreate the volume without it, stored credentials become unreadable.
cat <<'EOF' > .env # Public hostname n8n will be served from (no scheme) N8N_HOST=n8n.example.com # Timezone used by Cron and scheduling nodes GENERIC_TIMEZONE=UTC # Pin to a specific release for reproducible deploys, or leave as stable N8N_VERSION=stable # 64-char hex key that encrypts stored credentials. Generate once, back it up. N8N_ENCRYPTION_KEY=replace-with-openssl-rand-hex-32 EOF Start the stack:
docker compose up -d docker compose logs -f n8n You should see n8n report that the editor is ready on port 5678. It is not reachable from the internet yet — that is the next step.
Reverse proxy, HTTPS, and first-run hardening
n8n needs a proxy that forwards the original host and protocol, because it builds webhook URLs and OAuth callbacks from N8N_HOST and N8N_WEBHOOK_URL. If those are wrong, every webhook trigger silently points at the wrong place.
Caddy example (/etc/caddy/Caddyfile):
n8n.example.com { encode zstd gzip reverse_proxy 127.0.0.1:5678 { header_up X-Forwarded-Proto {scheme} header_up X-Forwarded-Host {host} } request_body { max_size 100MB } } Nginx equivalent:
server { listen 443 ssl http2; server_name n8n.example.com; ssl_certificate /etc/letsencrypt/live/n8n.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/n8n.example.com/privkey.pem; client_max_body_size 100M; location / { proxy_pass http://127.0.0.1:5678; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 3600s; } } The Upgrade/Connection headers and the long read timeout matter: the editor keeps a WebSocket open for live execution updates, and long-running workflows will drop the connection if the proxy times out at 60 seconds. The body size limit matters for file uploads and webhook payloads.
First-run hardening:
- Open
https://n8n.example.comand complete the owner account setup immediately. Until you do, anyone who reaches the URL can claim the instance. - If you need to delay setup, keep the proxy disabled or block the port at the firewall until you are ready.
- Store API keys and OAuth secrets as n8n credentials, not in environment variables — they are encrypted with
N8N_ENCRYPTION_KEYand survive restarts. - Restrict outbound traffic if workflows should only reach known APIs. n8n can call anything the container can reach.
Updating, backups, and common pitfalls
Update to the latest stable release:
cd ~/n8n-compose docker compose pull docker compose up -d docker compose logs -f n8n If you pinned N8N_VERSION, bump it in .env first. n8n ships a new minor version most weeks; read the release notes before jumping major versions, since node behavior and database migrations can change.
Back up the volume and your .env together — the encryption key in .env is useless without the database, and vice versa:
cd ~/n8n-compose docker compose stop n8n docker run --rm \ -v n8n-compose_n8n_data:/data \ -v "$PWD":/backup \ alpine tar czf /backup/n8n-data-$(date +%F).tar.gz -C /data . cp .env "backup/n8n-env-$(date +%F).env" docker compose start n8n Adjust the volume name if your project directory is not n8n-compose; check with docker volume ls. Restore by stopping n8n, extracting the tarball back into the volume, and starting again.
Two pitfalls worth knowing before you hit them:
- Webhook URL drift. If
N8N_HOSTorN8N_WEBHOOK_URLis wrong, the editor still works but every webhook trigger and OAuth redirect points at the wrong host. After changing either value, restart the container and re-check the webhook URL shown in the node panel. - File access scope.
N8N_RESTRICT_FILE_ACCESS_TO=/fileslimits the Read/Write Files node to the mounted directory. If you skip it, workflows can read and write anywhere the container user can reach, including the SQLite database and encryption key. Keep the restriction and put shared files under./local-files.
Measured in our sandbox run: total memory 638.3 MB (sum of per-container peaks over a 30s idle window after startup) across 1 container; largest container 638.3 MB; published port(s) 5678; HTTP probe returned 200. The run took 37.9s with the image already cached; a fresh server also has to download it. Required secret(s) N8N_HOST were generated for the test run, as the tutorial instructs.
Verification: we ran this docker-compose stack in a disposable Docker environment and recorded the measurements above. They describe that run, not a guarantee for your host.
Originally published with full interactive benchmark metrics and server sizing notes at https://benchrun.pages.dev/self-host-n8n-docker-vps/.
