Deployment Options
Relevant source files
The following files were used as context for generating this wiki page:
n8n provides multiple deployment methods to suit different environments, including Docker-based containerization, cloud-hosted options, and local development setups. These options support various database backends and configuration scales, from single-instance SQLite setups to multi-main PostgreSQL clusters.
Docker Deployment
Docker serves as the primary deployment method for n8n. Users can run n8n using standard Docker commands or orchestrate complex setups via Docker Compose.
Basic Docker Setup
A standard Docker deployment requires creating a persistent volume to store workflow data, the encryption key, and the SQLite database. By default, n8n saves data in the /home/node/.n8n directory within the 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
Sources: docker/images/n8n/README.md:65-74
Database Configuration
While n8n uses SQLite by default, it supports PostgreSQL for production environments. Configuration occurs via environment variables. Even with an external database, the /home/node/.n8n folder must remain persistent to preserve the encryption key used for credentials.
| Environment Variable | Description |
|---|---|
DB_TYPE | Set to postgresdb for PostgreSQL |
DB_POSTGRESDB_DATABASE | The name of the PostgreSQL database |
DB_POSTGRESDB_HOST | Database server hostname |
DB_POSTGRESDB_PORT | Database server port |
DB_POSTGRESDB_USER | Database username |
DB_POSTGRESDB_PASSWORD | Database password |
| Sources: docker/images/n8n/README.md:83-110 |
Sensitive Data Management
To avoid passing secrets via environment variables, n8n supports the _FILE suffix. Appending _FILE to a variable name instructs n8n to load the value from a specific file path, which is compatible with Docker and Kubernetes secrets.
Sources: docker/images/n8n/README.md:114-122
Development and Local Deployment
Local deployment is used for development, testing, and creating custom nodes. This requires Node.js (version 24+), pnpm, and specific build tools depending on the operating system.
Setup Process
- Install dependencies:
pnpm install - Build the project:
pnpm build - Start n8n:
pnpm start
Sources: CONTRIBUTING.md:104-120
Dev Containers
For developers using VS Code and Docker, a Dev Container configuration is available. This automatically installs required extensions and clones the source code into a container volume.
Sources: CONTRIBUTING.md:46-48
Local Configuration Workflow
The following diagram illustrates the local setup and build process for a development environment.
The diagram shows the sequence of commands required to initialize a local n8n instance from a source code clone.
Sources: CONTRIBUTING.md:139-150
Advanced Deployment Configurations
n8n supports advanced scaling options using Testcontainers for local stack testing and multi-main configurations.
Scaling and Stacks
Users can spin up different infrastructure stacks using the --filter n8n-containers flag:
- SQLite Stack:
pnpm --filter n8n-containers stack:sqlite - Postgres Stack:
pnpm --filter n8n-containers stack:postgres - Queue Mode:
pnpm --filter n8n-containers stack:queue - Multi-Main:
pnpm --filter n8n-containers stack:multi-main
Sources: CONTRIBUTING.md:252-276
Multi-Main Architecture
In a Multi-Main setup, n8n utilizes a load balancer to distribute traffic across multiple main instances.
The diagram represents a multi-main deployment where multiple n8n instances share a PostgreSQL database and Redis for state management.
Sources: CONTRIBUTING.md:278-283, AGENTS.md:129-130
Deployment Environment Variables
n8n uses environment variables to control global settings during deployment.
| Variable | Default | Description |
|---|---|---|
N8N_PORT | 5678 | Port for the backend server |
N8N_EDITOR_PORT | 8080 | Port for the editor UI dev server |
GENERIC_TIMEZONE | UTC | Timezone for nodes like Schedule |
TZ | - | System-level timezone for shell commands |
N8N_USER_FOLDER | ~/.n8n | Path to persistent data storage |
N8N_DEV_RELOAD | false | Enables hot reload for node development |
| Sources: CONTRIBUTING.md:131-135, docker/images/n8n/README.md:159-170, AGENTS.md:213-214 |
Summary
n8n offers flexible deployment options ranging from a simple Docker container with SQLite to complex, scalable multi-main environments using PostgreSQL and Redis. For development, the project supports localized builds, Dev Containers, and automated stack orchestration via Testcontainers, ensuring consistency across various environments.
Sources: docker/images/n8n/README.md:10-20, CONTRIBUTING.md:252-260