Deployment Options

Relevant source files

The following files were used as context for generating this wiki page:

• docker/images/n8n/README.md
• CONTRIBUTING.md
• packages/@n8n/benchmark/scripts/n8n-setups/postgres/docker-compose.yml
• README.md
• packages/@n8n/create-node/README.md
• AGENTS.md

n8n is a workflow automation platform designed for self-hosting, providing full control over data and infrastructure. This document outlines the primary methods for deploying and running an n8n instance, covering production scenarios with Docker and local setups for development and contribution.

The main deployment strategies include using Docker for single-container instances, Docker Compose for multi-service environments (like n8n with a PostgreSQL database), and setting up a local development environment from the source code. Configuration is primarily managed through environment variables, allowing for flexible and secure deployments.

Sources: README.md, docker/images/n8n/README.md

Docker Deployment

Docker is the recommended method for running n8n in production. It encapsulates the application and its dependencies into a standardized unit for software development.

Sources: docker/images/n8n/README.md:39-47

Quick Start with Docker

A single Docker command can start an n8n instance. The default setup uses an SQLite database for data persistence, which is stored in 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

This command performs the following actions:

1. Creates a named volume n8n_data to persist workflow data, credentials, and encryption keys.
2. Runs the n8n Docker image docker.n8n.io/n8nio/n8n.
3. Maps port 5678 on the host to port 5678 in the container.
4. Mounts the n8n_data volume to /home/node/.n8n inside the container, which is the default user data directory.

After running the command, n8n is accessible at http://localhost:5678.

Sources: docker/images/n8n/README.md:41-54

Data Persistence

Persisting the /home/node/.n8n directory is critical. This directory contains the SQLite database for workflows and past executions, as well as the encryption key for credentials. If this data is lost, existing credentials cannot be decrypted. Even when using an external database like PostgreSQL, this volume must be persisted.

Sources: docker/images/n8n/README.md:52-56, docker/images/n8n/README.md:61-64

Docker Image Versions

n8n provides several Docker image tags to control the version you deploy.

Tag	Description	Pull Command
latest	The latest stable version.	docker pull docker.n8n.io/n8nio/n8n
next	The latest unstable build with new features.	docker pull docker.n8n.io/n8nio/n8n:next
:[version]	A specific version, e.g., 0.220.1.	docker pull docker.n8n.io/n8nio/n8n:0.220.1

Sources: docker/images/n8n/README.md:92-104

Updating a Docker Container

To update an n8n instance running in Docker:

1. Pull the desired image version.
2. Stop the currently running container.
3. Remove the old container (this does not delete the data in the named volume).
4. Start a new container with the same docker run command used previously.

Sources: docker/images/n8n/README.md:106-121

Docker Compose Deployment

For more complex setups, such as running n8n with a dedicated database like PostgreSQL, docker-compose is recommended. It allows you to define and manage multi-container Docker applications.

Sources: docker/images/n8n/README.md:76-77

Example: n8n with PostgreSQL

The following is an example docker-compose.yml for running n8n with a PostgreSQL database. This setup is used for benchmarking but serves as a good production reference.

# packages/@n8n/benchmark/scripts/n8n-setups/postgres/docker-compose.yml
version: '3.8'

volumes:
  n8n_data:
  postgres-data:

services:
  postgres:
    image: postgres:11
    restart: always
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=n8n
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - n8n-test-network

  n8n:
    image: docker.n8n.io/n8nio/n8n:latest
    restart: always
    ports:
      - "5678:5678"
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=user
      - DB_POSTGRESDB_PASSWORD=password
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      - postgres
    networks:
      - n8n-test-network

networks:
  n8n-test-network:

Sources: packages/@n8n/benchmark/scripts/n8n-setups/postgres/docker-compose.yml

Architecture Diagram

The diagram below illustrates the components and data flow in the Docker Compose setup.

This diagram shows the user interacting with the n8n service, which in turn connects to the PostgreSQL service for database operations. Both services persist their data in dedicated Docker volumes.

Sources: packages/@n8n/benchmark/scripts/n8n-setups/postgres/docker-compose.yml

Updating with Docker Compose

Updating an n8n instance managed by Docker Compose is streamlined:

# Pull the latest version of the n8n image
docker compose pull

# Stop and remove the old containers
docker compose down

# Start the new containers
docker compose up -d

Sources: docker/images/n8n/README.md:123-131

Configuration

n8n is configured using environment variables. This is especially useful in Docker deployments to set database connections, timezones, and other operational parameters.

Key Environment Variables

Variable	Description	Example	Source File
DB_TYPE	Specifies the database to use.	postgresdb	docker/images/n8n/README.md:66
DB_POSTGRESDB_HOST	Hostname of the PostgreSQL server.	postgres	docker/images/n8n/README.md:68
DB_POSTGRESDB_DATABASE	The PostgreSQL database name.	n8n	docker/images/n8n/README.md:67
DB_POSTGRESDB_USER	Username for the PostgreSQL database.	user	docker/images/n8n/README.md:70
DB_POSTGRESDB_PASSWORD	Password for the PostgreSQL database.	password	docker/images/n8n/README.md:72
GENERIC_TIMEZONE	Sets the timezone for n8n-specific logic, like the Schedule node.	Europe/Berlin	docker/images/n8n/README.md:135-136
TZ	Sets the system's timezone.	Europe/Berlin	docker/images/n8n/README.md:138-139
N8N_DEV_RELOAD	Enables hot-reloading for custom node development.	true	CONTRIBUTING.md:112-115

Passing Secrets via Files

To enhance security, sensitive data like database passwords can be passed via files instead of environment variables. This is achieved by appending _FILE to the environment variable name. n8n will read the content of the specified file. This is particularly useful with Docker Secrets and Kubernetes Secrets.

Supported variables include:

• DB_POSTGRESDB_DATABASE_FILE
• DB_POSTGRESDB_HOST_FILE
• DB_POSTGRESDB_PASSWORD_FILE
• DB_POSTGRESDB_PORT_FILE
• DB_POSTGRESDB_USER_FILE
• DB_POSTGRESDB_SCHEMA_FILE

Sources: docker/images/n8n/README.md:79-89

Local Development Setup

For contributors or those wanting to run n8n from the source code, a local development environment can be set up. This method uses pnpm workspaces to manage the monorepo structure.

Sources: CONTRIBUTING.md:43-46

Requirements

• Node.js (version 22.16 or newer)
• pnpm (version 10.2 or newer), preferably installed via corepack
• Build tools (build-essential and python on Debian/Ubuntu)

Sources: CONTRIBUTING.md:52-78

Setup and Startup Flow

The following diagram illustrates the process of setting up and starting n8n for local development.

Development Commands

The project provides several pnpm scripts to manage the development lifecycle.

Command	Description
pnpm install	Installs all dependencies for all modules and links them.
pnpm build	Builds all packages in the monorepo.
pnpm start	Starts n8n in production mode after building.
pnpm dev	Starts n8n in development mode with hot-reloading for both frontend and backend.
pnpm dev:be	Runs backend-only development mode, excluding frontend packages.
pnpm dev:fe	Runs frontend-only development mode with a backend server.
pnpm dev:ai	Runs a focused development mode for AI/LangChain nodes.
npm create @n8n/node@latest	Scaffolds a new custom community node project.

Sources: CONTRIBUTING.md:97-109, CONTRIBUTING.md:124-142, packages/@n8n/create-node/README.md:5-7

Building a Custom Docker Image

If you need to build a custom Docker image (for example, with custom nodes included), the project provides a command to simplify this process. The build requires a pre-compiled n8n application.

The recommended command bundles the application compilation and Docker image creation:

pnpm build:docker

Alternatively, you can first compile the application and then build the image:

# 1. Compile the application
pnpm run build:deploy

# 2. Run your Docker build process, ensuring the 'compiled' directory is in the context.

Sources: docker/images/n8n/README.md:152-168