n8n on Debian 12: The Docker Method

n8n on Debian 12: The Docker Method #

This guide provides a robust method for installing, configuring, and managing n8n on a Debian 12 server using Docker. This setup is isolated, reproducible, and bypasses potential host system issues with Node.js/npm.

1. Prerequisites #

  • A server running Debian 12.
  • A user with sudo privileges (this guide uses dev).
  • A domain or subdomain ready to be pointed to the server’s IP.

2. Docker Installation #

2.1. Set up Docker’s APT Repository # 

# Update package index and install prerequisites
sudo apt-get update
sudo apt-get install -y ca-certificates curl

# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

2.2. Install Docker Engine and Compose # 

sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

2.3. Add User to Docker Group (Post-installation) #

This allows running Docker commands without sudo. You will need to log out and log back in for this change to take effect.

sudo usermod -aG docker $USER

3. n8n Deployment with Docker Compose #

3.1. Create Project Directory #

This directory will hold your Docker Compose configuration.

mkdir -p /home/dev/testing/n8n
cd /home/dev/testing/n8n

3.2. Create docker-compose.yml #

Create the Docker Compose file:

nano docker-compose.yml

Paste the following content. This configuration uses a persistent named volume (n8n_data) to ensure your n8n workflows and data are saved even if the container is removed or updated.

version: '3.8'

services:
  n8n:
    image: n8nio/n8n
    restart: always
    ports:
      # Exposes n8n on port 5678, but only accessible from the host machine itself.
      - "127.0.0.1:5678:5678"
    environment:
      # Sets the timezone for n8n. Adjust if necessary.
      - GENERIC_TIMEZONE="Europe/Berlin"
    volumes:
      # Mounts a persistent volume to store n8n data.
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:

3.3. Launch n8n #

From within the /home/dev/testing/n8n directory, run:

docker-compose up -d

4. Configure Nginx Reverse Proxy #

This makes n8n accessible via your domain and secures it with SSL.

4.1. Create Nginx Config #

Remember to replace n8n.example.com with your actual domain name.

sudo nano /etc/nginx/sites-available/n8n.example.com

Paste the following content. This proxies requests to the n8n container.

server {
    listen 80;
    server_name n8n.example.com; # <-- CHANGE THIS

    location / {
        proxy_pass http://localhost:5678;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

4.2. Enable Site & Secure with SSL # 

# Enable the site
sudo ln -s /etc/nginx/sites-available/n8n.example.com /etc/nginx/sites-enabled/

# Test configuration and restart Nginx
sudo nginx -t
sudo systemctl restart nginx

# Obtain SSL certificate (after pointing your domain)
sudo certbot --nginx -d n8n.example.com # <-- CHANGE THIS

5. Essential Docker Management Commands #

  • Check Container Status: cd /home/dev/testing/n8n && docker-compose ps
  • Start/Stop/Restart: cd /home/dev/testing/n8n && docker-compose start|stop|restart
  • View Logs: cd /home/dev/testing/n8n && docker-compose logs -f
  • Update n8n: cd /home/dev/testing/n8n && docker-compose pull && docker-compose up -d