Deployment with Docker
Relevant source files
The following files were used as context for generating this wiki page: - [docker/images/n8n/README.md](https://github.com/mrge-io/eval-n8n/blob/HEAD/docker/images/n8n/README.md) - [packages/@n8n/benchmark/scripts/n8n-setups/scaling-multi-main/docker-compose.yml](https://github.com/mrge-io/eval-n8n/blob/HEAD/packages/%40n8n/benchmark/scripts/n8n-setups/scaling-multi-main/docker-compose.yml) - [CONTRIBUTING.md](https://github.com/mrge-io/eval-n8n/blob/HEAD/CONTRIBUTING.md) - [packages/testing/containers/n8n-start-stack.ts](https://github.com/mrge-io/eval-n8n/blob/HEAD/packages/testing/containers/n8n-start-stack.ts) - [packages/testing/playwright/README.md](https://github.com/mrge-io/eval-n8n/blob/HEAD/packages/testing/playwright/README.md)Docker is the primary method for deploying n8n, offering flexibility for simple local instances, complex scaled-out production environments, and consistent development setups. It allows users to run n8n with full control over data and configuration, either locally or in the cloud.
This document outlines the various ways to deploy and manage n8n using Docker, from a single container to a multi-instance, queue-based architecture. It also covers configuration, data persistence, and updating strategies.
Basic Docker Deployment
The simplest way to start n8n is by using the docker run command. This downloads the official n8n image and starts a container.
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
This command starts an n8n instance accessible at http://localhost:5678.
Sources: docker/images/n8n/README.md:43-50
Data Persistence
To ensure that workflow data, credentials, and webhook URLs are saved between container restarts, it is critical to mount a volume to the /home/node/.n8n directory inside the container. This directory contains the SQLite database (if used) and the encryption key for credentials.
The following diagram illustrates the basic Docker deployment process.
Sources: docker/images/n8n/README.md:52-57
Tunnel for Local Development
For local development and testing webhooks, n8n can be started with a tunnel service that exposes the local instance to the internet. This is achieved by adding the start --tunnel command.
WARNING: This feature is intended for development and testing only and should not be used in production.
docker run -it --rm \
--name n8n \
-p 5678:5678 \
-v n8n_data:/home/node/.n8n \
docker.n8n.io/n8nio/n8n \
start --tunnel
Sources: docker/images/n8n/README.md:62-76
Configuration via Environment Variables
The n8n Docker container can be configured using environment variables passed with the -e flag in the docker run command.
Database Configuration
While n8n defaults to SQLite, it supports PostgreSQL for more robust deployments. To use PostgreSQL, you must set the appropriate DB_ environment variables.
| Variable | Description | Example |
|---|---|---|
DB_TYPE | The database type to use. | postgresdb |
DB_POSTGRESDB_HOST | The hostname of the PostgreSQL server. | postgres |
DB_POSTGRESDB_PORT | The port of the PostgreSQL server. | 5432 |
DB_POSTGRESDB_DATABASE | The database name. | n8n |
DB_POSTGRESDB_USER | The username for the database. | user |
DB_POSTGRESDB_PASSWORD | The password for the database user. | password |
DB_POSTGRESDB_SCHEMA | The database schema to use. | public |
Sources: docker/images/n8n/README.md:82-99
Passing Secrets via Files
To enhance security, sensitive data like database credentials can be passed via Docker secrets instead of environment variables. This is done by appending _FILE to the environment variable name and setting its value to the path of the secret file within the container.
Supported variables include:
DB_POSTGRESDB_DATABASE_FILEDB_POSTGRESDB_HOST_FILEDB_POSTGRESDB_PASSWORD_FILEDB_POSTGRESDB_PORT_FILEDB_POSTGRESDB_USER_FILEDB_POSTGRESDB_SCHEMA_FILE
Sources: docker/images/n8n/README.md:104-116
Timezone Configuration
The timezone for n8n and the underlying system can be set using GENERIC_TIMEZONE and TZ environment variables, respectively. This is important for nodes like Schedule to function correctly.
-e GENERIC_TIMEZONE="Europe/Berlin" \
-e TZ="Europe/Berlin"
Sources: docker/images/n8n/README.md:146-156
Deployment with Docker Compose
For multi-container setups, docker-compose is recommended. It simplifies the management of n8n along with its dependencies like a database.
Scaled Deployment (Queue Mode)
For high-performance and horizontally scaled environments, n8n can run in "queue mode". This architecture typically involves a load balancer, multiple main instances, multiple worker instances, a Redis instance for queuing, and a PostgreSQL database.
The packages/@n8n/benchmark/scripts/n8n-setups/scaling-multi-main/docker-compose.yml file provides an example of such a setup.
The following diagram illustrates the architecture of a scaled n8n deployment using Docker Compose.
This diagram shows how user requests are distributed by a load balancer to multiple main n8n instances, which then offload workflow executions to worker instances via a Redis queue. All instances share a common PostgreSQL database for state and data.
Sources: packages/@n8n/benchmark/scripts/n8n-setups/scaling-multi-main/docker-compose.yml
The key services in this docker-compose.yml are:
| Service | Image | Purpose |
|---|---|---|
postgres | postgres:14 | The central database for storing workflows, credentials, and execution data. |
redis | redis:7 | A message broker used to manage the execution queue for workers. |
n8n-main-1, n8n-main-2 | n8nio/n8n:local | Main n8n instances that handle the UI, API, and webhook triggers. They enqueue jobs for workers. |
n8n-worker-1, n8n-worker-2 | n8nio/n8n:local | Worker instances that dequeue and execute workflows. |
traefik | traefik:v2.5 | A reverse proxy and load balancer that routes incoming traffic to the main instances. |
Sources: packages/@n8n/benchmark/scripts/n8n-setups/scaling-multi-main/docker-compose.yml:11-100
Updating Docker Deployments
To update an n8n instance to a newer version, you need to pull the latest Docker image and recreate the container.
Using docker CLI
-
Pull the latest image:
docker pull docker.n8n.io/n8nio/n8nTo pull a specific version, use a tag like
docker.n8n.io/n8nio/n8n:0.220.1. -
Stop and remove the old container:
docker stop <container_id> docker rm <container_id> -
Start a new container with the same
docker runcommand used for the initial setup.
Sources: docker/images/n8n/README.md:124-144
Using docker-compose
Updating with Docker Compose is simpler:
# Pull the latest versions of all services
docker compose pull
# Stop and remove the old containers
docker compose down
# Start the new containers
docker compose up -d
This process is illustrated in the sequence diagram below.
Sources: docker/images/n8n/README.md:146-156
Development and Testing
Docker is integral to the n8n development and testing process, ensuring a consistent environment.
Dev Container
The repository is configured to use VS Code Dev Containers. This allows developers to quickly spin up a pre-configured development environment inside a Docker container with all necessary dependencies installed.
Sources: CONTRIBUTING.md:52-55
Building the Docker Image
A local Docker image can be built from the source code. This requires a pre-compiled n8n application. The recommended command handles both compilation and image creation:
pnpm build:docker
Sources: docker/images/n8n/README.md:162-171
Test Stacks
The project includes scripts to programmatically start various Docker-based n8n stacks for testing purposes, including for E2E and performance tests. The n8n-start-stack.ts script can configure stacks with different databases and scaling options.
The Playwright test suite uses these stacks to run tests against different configurations:
pnpm test:container:standard(SQLite)pnpm test:container:postgres(PostgreSQL)pnpm test:container:queue(Queue mode)
Sources: packages/testing/containers/n8n-start-stack.ts, packages/testing/playwright/README.md:13-16
Conclusion
Deploying n8n with Docker provides a powerful and scalable solution suitable for a wide range of use cases. Users can start with a simple single-container instance and scale up to a resilient, multi-instance, queue-based architecture as their needs grow. The use of environment variables and Docker Compose files allows for flexible and maintainable configurations, while integration into the development and testing workflows ensures consistency across the entire lifecycle of the application.