Skip to main content

n8n Docker Installation Guide

This guide will walk you through setting up n8n, a powerful workflow automation tool, using Docker Compose. Self-hosting n8n gives you complete control over your data and environment.

Features

n8n offers a robust set of features for automating tasks and integrating various services:

  • Low-Code/No-Code Interface: Visually build workflows by connecting "nodes" with a drag-and-drop interface, making automation accessible to users with varying technical expertise.

  • Code Extensibility: For more complex scenarios, you can extend n8n's functionality by writing custom JavaScript or Python code within "Code" nodes.

  • Extensive Integrations: Connect to hundreds of popular applications, APIs, and databases with pre-built nodes. If a direct integration isn't available, you can use the HTTP Request node to interact with any API.

  • Self-Hostable & Open-Source: Enjoy full ownership and control over your data and workflows by hosting n8n on your own server. The open-source nature allows for transparency and community contributions.

  • Event-Driven Workflows: Trigger workflows based on various events (e.g., webhooks, scheduled times, new data in an application) or run them on demand.

  • Data Persistence: With Docker volumes, your workflow data, credentials, and execution history are persisted even if the n8n container is restarted or updated.

  • Scalability: Docker Compose provides a good foundation for scaling your n8n instance if your automation needs grow.

Prerequisites

Before you begin, ensure you have the following installed on your server or local machine:

  • Docker: The Docker engine is required to run n8n containers.

  • Docker Compose: This tool allows you to define and run multi-container Docker applications.

  • Basic Terminal/CLI Knowledge: Familiarity with navigating directories and executing commands in a terminal.

  • Minimum System Resources: At least 1GB RAM and 1 vCPU are recommended.

  • Cloudflare Account and Registered Domain: If you plan to use Cloudflare Tunnel, you will need an active Cloudflare account and a domain managed by Cloudflare.

Follow these steps to install n8n using Docker Compose:

Step 1: Create a Directory for n8n

First, create a directory where your n8n configuration and data will be stored. This ensures data persistence.

mkdir n8n-data
cd n8n-data
Step 2: Create a .env file

In the n8n-data directory, create a file named .env. This file will store your environment variables, including your n8n credentials and Cloudflare Tunnel token. Make sure to replace placeholder values with your actual strong, unique credentials and Cloudflare details.

# .env file for n8n Docker Compose setup

# --- n8n Basic Authentication Credentials ---
# IMPORTANT: Change these to strong, unique values!
N8N_USER=yourusername
N8N_PASSWORD=yourstrongpassword

# --- n8n Hostname Configuration (for webhooks) ---
# For production, replace example.com with your actual domain.
# SUBDOMAIN can be empty for the root domain (e.g., example.com) or a subdomain (e.g., n8n)
SUBDOMAIN=n8n # e.g., 'n8n' for n8n.example.com
DOMAIN_NAME=example.com # e.g., 'example.com'

# --- Cloudflare Tunnel Configuration ---
# Your Cloudflare Tunnel token. Obtain this from the Cloudflare dashboard when creating a new tunnel.
# Example: eyJhIjoiMzc3YjY1.....
TUNNEL_TOKEN=your_cloudflare_tunnel_token_here
Step 3: Create a docker-compose.yml file

Inside the n8n-data directory, create a file named docker-compose.yml and paste the following content into it. This configuration includes both the n8n service and a cloudflared service to expose n8n securely via Cloudflare Tunnel.

version: '3.8' # Specify the Docker Compose file format version

services:
  n8n:
    image: n8nio/n8n:latest # Use the official n8n Docker image. ':latest' pulls the most recent stable version.
    container_name: n8n # Assign a name to your container for easy identification
    restart: unless-stopped # Automatically restart the container unless it's explicitly stopped
    ports:
      # n8n will be accessed via Cloudflare Tunnel, so direct port exposure is not strictly necessary for external access.
      # However, keeping it for local access or debugging is often useful.
      - "127.0.0.1:5678:5678" # Map port 5678 on localhost to port 5678 in the container.
    environment:
      # General n8n configuration
      - N8N_HOST=${SUBDOMAIN}.${DOMAIN_NAME} # Hostname for n8n. Used for webhooks.
      - N8N_PORT=5678 # Port n8n listens on inside the container
      - N8N_PROTOCOL=http # Protocol for n8n (http or https)
      - NODE_ENV=production # Set to 'production' for optimized performance
      - GENERIC_TIMEZONE=Asia/Manila # Set your desired timezone (e.g., Europe/Berlin, America/New_York). This affects schedule nodes.
      - N8N_BASIC_AUTH_ACTIVE=true # Enable basic authentication for security
      - N8N_BASIC_AUTH_USER=${N8N_USER} # Username for basic authentication (read from .env)
      - N8N_BASIC_AUTH_PASSWORD=${N8N_PASSWORD} # Password for basic authentication (read from .env)
      - DB_TYPE=sqlite # Use SQLite for database (default and simplest option)
      - N8N_METRICS_ENABLED=false # Disable metrics for simpler setups
      - N8N_DIAGNOSTICS_ENABLED=false # Disable diagnostics for privacy
      - N8N_LOG_LEVEL=info # Set logging level (debug, info, warn, error)

      # Cloudflare Tunnel configuration for n8n webhooks
      # This tells n8n to use the Cloudflare Tunnel URL for its webhooks.
      - WEBHOOK_TUNNEL_URL=https://${SUBDOMAIN}.${DOMAIN_NAME} # This will be the public URL for your n8n instance

    volumes:
      # Mount a named volume to persist n8n data (workflows, credentials, executions)
      - n8n_data:/home/node/.n8n

  cloudflared:
    image: cloudflare/cloudflared:latest # Official Cloudflare Tunnel Docker image
    container_name: cloudflared # Name for the Cloudflare Tunnel container
    restart: unless-stopped # Automatically restart the container unless it's explicitly stopped
    environment:
      - TUNNEL_TOKEN=${TUNNEL_TOKEN} # Your Cloudflare Tunnel token from the .env file
    command: tunnel run --token ${TUNNEL_TOKEN} # Command to run the tunnel with the provided token
    depends_on:
      - n8n # Ensure n8n starts before cloudflared attempts to connect
    networks:
      - default # Use the default Docker network to communicate with n8n

networks:
  default: # Define the default network for services to communicate

volumes:
  n8n_data: # Define the named volume for n8n data persistence
Step 4: Configure Cloudflare Tunnel

A quick way to expose and get it up and running with a valid certificate is by setting up a Cloudflare Tunnel:

  1. Log in to Cloudflare: Go to your Cloudflare dashboard.

  2. Navigate to Zero Trust: In the left sidebar, click on "Zero Trust".

  3. Create a Tunnel: Go to "Access" > "Tunnels" and click "Create a tunnel".

  4. Name Your Tunnel: Give your tunnel a memorable name (e.g., homelab-tunnel).

  5. Choose Docker: Select "Docker" as your environment. Cloudflare will provide a TUNNEL_TOKEN. Copy this token.

  6. Update .env: Paste the copied TUNNEL_TOKEN into the TUNNEL_TOKEN variable in your .env file.

  7. Configure Public Hostname: In the Cloudflare Tunnel setup, you'll configure a public hostname.

    • Subdomain: Enter the SUBDOMAIN you defined in your .env file (e.g., n8n).

    • Domain: Select your DOMAIN_NAME from the dropdown (e.g., example.com).

    • Service:

      • Type: HTTP

      • URL: http://n8n:5678 (This tells Cloudflare Tunnel to forward requests to the n8n service within your Docker network on port 5678).

    • Click "Save hostname" and then "Save tunnel".

Step 5: Start n8n and Cloudflare Tunnel

Now, from within the n8n-data directory (where your docker-compose.yml and .env files are located), run the following command to start both n8n and the Cloudflare Tunnel:

docker compose up -d

Docker will download the necessary images, create the n8n_data volume, and start both the n8n and cloudflared containers.

Step 6: Access n8n

Once the containers are running and the Cloudflare Tunnel is active, you can access the n8n web interface by opening your web browser and navigating to the domain you configured in Cloudflare (e.g., https://n8n.example.com).

You will be prompted to log in with the N8N_USER and N8N_PASSWORD you set in your .env file.

Back to top