Running n8n with Docker Compose gives you a repeatable way to manage the application, persistent data, configuration, and upgrades. The important part is not only starting the container. You also need to protect the n8n data directory, configure the public URL correctly, and avoid exposing the editor directly to the internet.
This guide shows a conservative Docker Compose setup for a small self-hosted n8n instance. It uses a named volume, an environment file for configuration, a healthcheck, and a reverse proxy for HTTPS.
What this setup provides
The example below gives you:
- a persistent n8n data volume;
- a restart policy;
- a clear public hostname configuration;
- a healthcheck for readiness visibility;
- a separate PostgreSQL option for larger or more important installations;
- commands to validate the final Compose configuration.
It does not automatically make an installation secure or production-ready. You still need to configure HTTPS, access control, backups, updates, and monitoring for your environment.
Prerequisites
You need:
- Docker Engine with the Compose plugin;
- a Linux server or local machine;
- a hostname if the instance must be reachable from the internet;
- a reverse proxy or another TLS termination method for HTTPS;
- a backup location for n8n data and credentials.
Check that Docker and Compose are available:
docker version
docker compose version
Do not publish an n8n editor to the public internet without planning authentication and HTTPS first.
Minimal local setup
Create a directory for the Compose project:
mkdir n8n-compose
cd n8n-compose
Create a .env file for non-secret configuration and local values:
N8N_HOST=localhost
N8N_PORT=5678
N8N_PROTOCOL=http
WEBHOOK_URL=http://localhost:5678/
GENERIC_TIMEZONE=UTC
Then create compose.yml:
services:
n8n:
image: docker.n8n.io/n8nio/n8n:latest
restart: unless-stopped
ports:
- "127.0.0.1:5678:5678"
environment:
N8N_HOST: ${N8N_HOST}
N8N_PORT: ${N8N_PORT}
N8N_PROTOCOL: ${N8N_PROTOCOL}
WEBHOOK_URL: ${WEBHOOK_URL}
GENERIC_TIMEZONE: ${GENERIC_TIMEZONE}
volumes:
- n8n_data:/home/node/.n8n
healthcheck:
test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://127.0.0.1:5678/healthz || exit 1"]
interval: 30s
timeout: 5s
retries: 5
start_period: 20s
volumes:
n8n_data:
The 127.0.0.1 binding keeps the editor reachable only from the server itself. A reverse proxy can then expose the HTTPS hostname without publishing port 5678 on every network interface.
The exact health endpoint and available utilities can vary by image version. If the image does not contain wget or the endpoint is not available in your version, replace the probe with a supported check rather than increasing retries until the error disappears.
Start and inspect n8n
Validate the resolved Compose file before starting it:
docker compose config
Start the service in the background:
docker compose up -d
Check container state:
docker compose ps
docker inspect --format '{{json .State.Health}}' n8n-compose-n8n-1
View startup logs:
docker compose logs --tail 100 n8n
Follow new log lines while diagnosing a problem:
docker compose logs -f --tail 100 n8n
- For more detailed log commands, see Docker Compose Logs.
Persistent n8n data
The named volume is mounted at n8n’s data directory:
volumes:
- n8n_data:/home/node/.n8n
This directory contains important instance data, including workflows and credentials managed by n8n. A container recreation should not be treated as a backup strategy. Back up the volume or use an appropriate export and restore procedure before upgrades and infrastructure changes.
List the volume:
docker volume ls
docker volume inspect n8n-compose_n8n_data
Do not run commands such as docker compose down -v casually. Removing the volume can remove the persistent data associated with the Compose project.
- For database persistence concepts, see Postgres Docker Compose and Docker Compose Volumes.
HTTPS and reverse proxy
For an internet-facing instance, terminate TLS at a reverse proxy. Keep n8n bound to localhost and proxy the public hostname to the local port.
A minimal Caddy example is:
n8n.example.com {
reverse_proxy 127.0.0.1:5678
}
Set the public URL values to match the real HTTPS hostname:
N8N_HOST=n8n.example.com
N8N_PORT=5678
N8N_PROTOCOL=https
WEBHOOK_URL=https://n8n.example.com/
The public webhook URL must match the address that external services can reach. A wrong protocol, hostname, or trailing path can make webhook-based workflows fail even when the editor opens correctly.
After changing environment values, recreate the container:
docker compose up -d --force-recreate
Do not expose the editor through a plain HTTP public URL. HTTPS protects the login session and data in transit, but it does not replace strong account security or a network access policy.
Environment variables and secrets
Use .env for configuration that is safe to keep locally, such as the hostname, protocol, and timezone. Keep passwords, encryption keys, and tokens out of committed files.
Add sensitive local files to .gitignore:
.env.local
.env.production
*.secret
You can use a separate local file for secrets, but confirm how your Compose version loads and passes each file. The .env file is commonly used for Compose interpolation; it is not automatically the same thing as an environment file passed into every container.
Before starting the service, inspect the resolved configuration carefully:
docker compose config
- Do not paste the output into public tickets or chats if it contains credentials or private URLs. For a broader explanation of
.env,env_file, and substitution, see Docker Compose Environment Variables.
When to use PostgreSQL
The embedded SQLite-based setup can be useful for a small local instance or a low-risk evaluation. A more important or busier installation may need an external database design, backups, and an explicit migration plan.
A PostgreSQL service can be added only after deciding how you will manage:
- database credentials;
- persistent database storage;
- backups and restore tests;
- upgrades and compatibility;
- network access between n8n and PostgreSQL;
- encryption and access control.
A healthcheck can tell Compose that PostgreSQL accepts connections, but it does not prove that every n8n migration has completed. Keep schema migrations and application startup behavior separate from a simple readiness probe.
Safe update workflow
Before updating the image:
docker compose ps
docker compose config
docker volume inspect n8n-compose_n8n_data
Create and verify a backup according to your storage process. Then pull the selected image and recreate the service:
docker compose pull n8n
docker compose up -d n8n
docker compose ps
docker compose logs --tail 100 n8n
Avoid using the floating latest tag when you need tightly controlled and repeatable deployments. Pinning a tested version makes rollback and troubleshooting easier, but you must maintain the version deliberately.
After an update, check:
docker compose ps
docker compose logs --tail 200 n8n
Then open a low-risk workflow and confirm the editor, credentials, executions, and webhook behavior before relying on the instance.
Common problems
The editor opens but webhooks fail
Check N8N_HOST, N8N_PROTOCOL, and WEBHOOK_URL. The webhook URL must use the public HTTPS address, not localhost or an internal container name.
The container is running but unhealthy
Inspect the health output and logs:
docker inspect --format '{{json .State.Health}}' n8n-compose-n8n-1
docker compose logs --tail 100 n8n
The command may be missing, the endpoint may differ, or n8n may still be starting. Fix the actual cause instead of masking it with an unlimited retry count.
Workflows disappeared after recreation
Check whether the volume is still attached:
docker volume ls
docker volume inspect n8n-compose_n8n_data
A changed Compose project name, a different working directory, or down -v can result in a different or removed volume. Restore from a known backup if data was deleted.
n8n cannot write its data directory
Check the container logs and the mounted volume permissions. Do not solve a permissions problem by making the whole host filesystem writable. Correct the ownership and mount scope for the intended n8n data directory.
The service is exposed unexpectedly
Check the port binding in the resolved configuration:
docker compose config
Prefer 127.0.0.1:5678:5678 behind a reverse proxy unless direct network exposure is deliberate and protected.
Practical checklist
Before calling a Compose deployment ready, verify:
-
docker compose configsucceeds; - n8n data is stored on a persistent volume;
- the volume has a tested backup;
- port
5678is not publicly exposed by accident; - HTTPS works at the public hostname;
-
WEBHOOK_URLmatches that hostname; - health status and logs are observable;
- credentials are not committed to Git;
- image updates have a rollback plan;
- a test workflow and webhook have been checked after changes.
Frequently Asked Questions
Is Docker Compose enough for a production n8n installation?
No. Compose manages the service definition, but production readiness also requires HTTPS, access control, backups, updates, monitoring, and a recovery plan.
Where does n8n store its persistent data?
In the mounted n8n data directory, commonly /home/node/.n8n in the container. Mount that path to a persistent volume and back it up.
Should port 5678 be public?
Usually not when a reverse proxy is used. Bind it to 127.0.0.1 and expose the service through the proxy with HTTPS.
Does a healthcheck restart n8n?
No. It reports health status. The restart policy and application behavior are separate concerns.
Can I use SQLite for n8n?
It can be suitable for some small or local installations. For more important workloads, evaluate PostgreSQL, backups, migrations, and operational requirements before choosing a database.
Summary
A reliable n8n Docker Compose setup starts with persistent data, a correct public URL, safe port binding, HTTPS, observable health, and tested backups. Validate the resolved configuration before starting the container, inspect logs when readiness fails, and treat upgrades as controlled changes rather than simply replacing the image.