🛠️ Step-by-Step Tutorial: Setting up n8n with Docker Compose

Using Docker Compose is the recommended method for self-hosting n8n, as it allows you to define the n8n application and its database (for persistence) in a single, manageable file.

Here is a step-by-step tutorial to get your n8n instance up and running.

Prerequisites

1. Docker: Must be installed and running on your server or local machine (Windows, macOS, or Linux).

2. Docker Compose: Usually comes bundled with Docker Desktop or can be installed separately.

Step 1: Create a Project Directory

First, create a dedicated folder for your n8n configuration and navigate into it. This will host your docker-compose.yml file and persistent data.

mkdir n8n-selfhosted
cd n8n-selfhosted

Step 2: Create the docker-compose.yml File

This file defines the services needed: the PostgreSQL database (to store your workflows and credentials persistently) and the n8n application itself.

Create a file named docker-compose.yml in your n8n-selfhosted directory and paste the following content. Make sure to change the POSTGRES_PASSWORD and N8N_BASIC_AUTH_PASSWORD to strong, secure values.

version: '3.8'

services:
  # The PostgreSQL Database Service
  db:
    image: postgres:15
    restart: always
    environment:
      # !! CHANGE THESE TO SECURE VALUES !!
      - POSTGRES_USER=n8n
      - POSTGRES_PASSWORD=your_secure_db_password
      - POSTGRES_DB=n8n
    volumes:
      # Persists the PostgreSQL data
      - postgres_data:/var/lib/postgresql/data

  # The n8n Application Service
  n8n:
    image: n8nio/n8n:latest
    restart: always
    ports:
      # Host Port:Container Port
      - "5678:5678"
    environment:
      # Database Configuration
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=db
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=your_secure_db_password
      # Basic Authentication for the Web UI
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=your_secure_ui_password
      # Timezone setting (e.g., Europe/London)
      - GENERIC_TIMEZONE=UTC
    volumes:
      # Persists n8n configuration, custom nodes, and credentials
      - n8n_data:/home/node/.n8n
    depends_on:
      - db
    
volumes:
  postgres_data:
  n8n_data:

Step 3: Start the n8n Stack

From the same directory (n8n-selfhosted) where you saved the docker-compose.yml file, execute the following command:

docker compose up -d

• docker compose up: Reads the docker-compose.yml file, pulls the specified images, and creates/starts the services.

• -d: Runs the containers in detached mode (in the background).

Wait a few moments for the images to download and the services to start.

Step 4: Access the n8n Web Interface

Once the containers are running, you can access your n8n instance:

1. Open your web browser.

2. Navigate to http://localhost:5678 (If running on a remote server, replace localhost with your server’s IP address or domain).

3. You will be prompted to log in using the Basic Auth credentials you set in the docker-compose.yml file:

   • Username: admin (or whatever you set for N8N_BASIC_AUTH_USER)

   • Password: your_secure_ui_password (or whatever you set for N8N_BASIC_AUTH_PASSWORD)

Step 5: Stopping and Updating n8n

To Stop n8n

To stop the running containers:

docker compose down

To Update n8n

To update n8n to the latest version while keeping your workflows and data safe (due to the persistent volumes):

1. Pull the latest image:

   Bash

    

   docker compose pull n8n
   

2. Restart the stack:

   Bash

    

   docker compose up -d