Docker Deployment & Configuration
Relevant source files
The following files were used as context for generating this wiki page:
n8n utilizes Docker to provide a consistent, containerized environment for workflow automation. Docker deployment allows technical teams to maintain full control over data, deployments, and scaling while simplifying the setup of complex dependencies like Node.js and Python.
Quick Start and Basic Setup
You can start an n8n instance quickly using the official Docker image. To ensure data persistence across container restarts, you must create and mount a Docker volume.
docker volume create n8n_data
docker run -it --rm \
--name n8n \
-p 5678:5678 \
-v n8n_data:/home/node/.n8n \
docker.n8n.io/n8nio/n8n
Sources: docker/images/n8n/README.md:61-71
Data Persistence
The /home/node/.n8n directory contains essential user data, including:
- SQLite Database: Stores workflows, past executions, and credentials.
- Encryption Key: Secures credentials; if this key is lost, existing credentials cannot be decrypted.
- Webhook URL: Configuration for incoming triggers.
Sources: docker/images/n8n/README.md:73-80
Database Configuration
While n8n uses SQLite by default, it supports PostgreSQL for production environments. Even when using an external database, you must still persist the /home/node/.n8n folder to keep the encryption key.
PostgreSQL Integration
To use PostgreSQL, define the connection parameters via environment variables.
docker run -it --rm \
--name n8n \
-p 5678:5678 \
-e DB_TYPE=postgresdb \
-e DB_POSTGRESDB_DATABASE=<POSTGRES_DATABASE> \
-e DB_POSTGRESDB_HOST=<POSTGRES_HOST> \
-e DB_POSTGRESDB_PORT=<POSTGRES_PORT> \
-e DB_POSTGRESDB_USER=<POSTGRES_USER> \
-e DB_POSTGRESDB_PASSWORD=<POSTGRES_PASSWORD> \
-v n8n_data:/home/node/.n8n \
docker.n8n.io/n8nio/n8n
Sources: docker/images/n8n/README.md:82-103
Sensitive Data via Files
n8n supports loading sensitive database configuration from files to accommodate Docker or Kubernetes secrets. You achieve this by appending _FILE to the environment variable name.
| Environment Variable | Description |
|---|---|
DB_POSTGRESDB_DATABASE_FILE | Path to file containing DB name |
DB_POSTGRESDB_HOST_FILE | Path to file containing DB host |
DB_POSTGRESDB_PASSWORD_FILE | Path to file containing DB password |
DB_POSTGRESDB_USER_FILE | Path to file containing DB user |
Sources: docker/images/n8n/README.md:105-115
Deployment Architectures
n8n supports various deployment topologies, ranging from single instances to multi-main stacks with load balancers.
Multi-Main Configuration
In high-availability setups, n8n runs multiple "main" instances. A load balancer distributes traffic, and each instance matches its webhook URL to the main URL.
The diagram shows a multi-main architecture where a load balancer distributes requests to redundant n8n instances sharing a common database and data volume.
Sources: CONTRIBUTING.md:255-263, packages/quality/testing/playwright/fixtures/base.ts:60-65
Image Management and Updates
n8n provides different image tags for stability and specific use cases.
Available Tags
- Latest/Stable:
docker.n8n.io/n8nio/n8n - Specific Version:
docker.n8n.io/n8nio/n8n:0.220.1 - Next (Unstable):
docker.n8n.io/n8nio/n8n:next - PC Tags: Suffix
-pc(e.g.,2.36.0-pc) are internal cloud variants and are not supported for general use.
Sources: docker/images/n8n/README.md:126-140
Update Procedure
To update n8n, pull the new image and recreate the container.
docker pull docker.n8n.io/n8nio/n8n
docker stop n8n
docker rm n8n
docker run --name=n8n [options] -d docker.n8n.io/n8nio/n8n
Sources: docker/images/n8n/README.md:144-158
Development and Testing Containers
For development, n8n provides specialized commands and containers to facilitate testing across different configurations.
Automated Testing Stacks
Developers can spin up specific stacks using pnpm filters to test various backends.
| Command | Stack Type |
|---|---|
pnpm --filter n8n-containers stack:sqlite | Basic SQLite setup |
pnpm --filter n8n-containers stack:postgres | PostgreSQL backend |
pnpm --filter n8n-containers stack:queue | Scaled worker queue setup |
pnpm --filter n8n-containers stack:multi-main | Multi-node main instances |
Sources: CONTRIBUTING.md:240-255
Building Custom Images
When building from source, n8n requires a pre-compiled application. The recommended command handles both compilation and image creation.
pnpm build:docker
Sources: docker/images/n8n/README.md:185-195, packages/cli/src/modules/source-control.ee/README.md:19-20
Environmental Configuration
n8n behavior is tuned via environment variables passed to the Docker container.
Timezone Settings
| Variable | Usage |
|---|---|
GENERIC_TIMEZONE | Sets the timezone for n8n logic (e.g., Schedule node) |
TZ | Sets the system timezone for the container OS |
Sources: docker/images/n8n/README.md:168-176
Hot Reloading
The N8N_DEV_RELOAD variable enables a file watcher. This allows the container to detect node changes without a full restart, which is particularly useful when developing custom nodes.
Sources: CONTRIBUTING.md:197-205
Conclusion
Docker deployment is the primary method for hosting n8n in production. By utilizing volumes for persistence, configuring external databases like PostgreSQL, and managing timezones and security keys through environment variables, administrators can deploy robust and scalable automation infrastructure.