Docker Compose provides a powerful way to run n8n with custom configurations and additional NPM modules. This guide will walk you through setting up a production-ready n8n instance using Docker Compose, complete with custom modules and advanced configurations.

For a more basic setup using Docker without custom NPM modules, see How to install n8n on a Local Server and Access it Securely from Anywhere

Prerequisites

• Docker and Docker Compose installed on your system
• Basic understanding of container orchestration
• Server with sufficient resources (minimum 2GB RAM recommended)
• Domain name configured with DNS records (for HTTPS access)

Why You Might Need to Use Docker Compose

Docker Compose becomes essential when you need to extend n8n’s capabilities with custom NPM modules. For example, in our implementation, we needed several specific tools:

• Content conversion tools (@tryfabric/martian and notion-to-md) for transforming Notion pages to JSON and HTML for websites
• Notion API client (@notionhq/client) for direct integration with Notion
• Markdown processing (markdown-it) for content formatting
• Media processing tools (ffmpeg) for extracting audio from video calls for transcription

By using Docker Compose, you can easily manage these dependencies in a reproducible way, ensuring that all necessary tools are properly installed and configured in your n8n environment. This approach offers flexibility to add any NPM packages you need for your specific automation workflows.

Project Structure Setup

First, let’s create a proper directory structure for our n8n deployment:

mkdir n8n-docker
cd n8n-docker
touch docker-compose.yml
touch Dockerfile
touch .env

Creating the Dockerfile

The Dockerfile allows us to extend the base n8n image with custom NPM packages:

FROM n8nio/n8n:latest

USER root

# Install additional npm packages
RUN npm install -g npm \
    @tryfabric/martian \
    notion-to-md \
    # Add other packages as needed

USER node

Docker Compose Configuration

Create a comprehensive docker-compose.yml file that includes all necessary configurations:

version: '3.8'

services:
  n8n:
    container_name: n8n
    build: .
    restart: always
    ports:
      - "5678:5678"
    environment:
      - NODE_FUNCTION_ALLOW_EXTERNAL=*
      - N8N_HOST=${N8N_HOST}
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - NODE_ENV=production
      - WEBHOOK_URL=https://${N8N_WEBHOOK_URL}/
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      # Email configuration
      - N8N_EMAIL_MODE=${N8N_EMAIL_MODE}
      - N8N_SMTP_HOST=${N8N_SMTP_HOST}
      - N8N_SMTP_PORT=${N8N_SMTP_PORT}
      - N8N_SMTP_USER=${N8N_SMTP_USER}
      - N8N_SMTP_PASS=${N8N_SMTP_PASS}
      - N8N_SMTP_SENDER=${N8N_SMTP_SENDER}
    volumes:
      - n8n_data:/home/node/.n8n
      - ${DATA_FOLDER}/files:/files
    networks:
      - n8n-network

networks:
  n8n-network:
    driver: bridge

volumes:
  n8n_data:
    external: true

Important: The environment variable NODE_FUNCTION_ALLOW_EXTERNAL=* is crucial for this setup to work properly. This setting allows n8n to use external NPM modules in your workflows. Without this configuration, any custom NPM packages installed in the Dockerfile will not be accessible within n8n functions.

Make sure to include NODE_FUNCTION_ALLOW_EXTERNAL=* in your environment variables. This is a required setting when working with custom NPM modules, and your workflows may fail if this is not properly configured.

Environment Configuration

Create a .env file with your specific configurations:

# Base Configuration
DATA_FOLDER=/path/to/your/data
N8N_HOST=your-domain.com
N8N_WEBHOOK_URL=your-domain.com
N8N_ENCRYPTION_KEY=your-secure-encryption-key

# Email Configuration
N8N_EMAIL_MODE=smtp
N8N_SMTP_HOST=smtp.provider.com
N8N_SMTP_PORT=587
N8N_SMTP_USER=your-smtp-user
N8N_SMTP_PASS=your-smtp-password
N8N_SMTP_SENDER=Your Name <name@domain.com>

Deployment Steps

1. Initialize the Volume

Create the external volume for persistent data storage:

docker volume create n8n_data

2. Build and Deploy

Start the n8n container with Docker Compose:

docker compose up -d --build

Maintenance and Updates

Updating n8n

To update your n8n installation:

# Pull the latest images
docker compose pull

# Rebuild and restart containers
docker compose down
docker compose up -d --build

Backup and Restore

Regular backups are crucial. Here’s how to backup your n8n data:

# Backup
docker run --rm -v n8n_data:/source -v $(pwd):/backup alpine tar czf /backup/n8n-backup.tar.gz -C /source .

# Restore
docker run --rm -v n8n_data:/target -v $(pwd):/backup alpine sh -c "cd /target && tar xzf /backup/n8n-backup.tar.gz"

Advanced Configurations

Custom NPM Modules

To add new NPM modules, update your Dockerfile and rebuild:

# Update Dockerfile with new packages
docker compose down
docker compose up -d --build

Troubleshooting

• Container won’t start: Check logs using docker compose logs n8n
• Permission issues: Ensure proper volume permissions and ownership
• Network connectivity: Verify network configuration and firewall settings

Security Best Practices

• Always use HTTPS in production
• Regularly update all components
• Use strong encryption keys
• Implement proper access controls

Conclusion

Running n8n with Docker Compose provides a robust, scalable, and maintainable automation platform. This setup enables you to leverage custom NPM modules while maintaining a production-ready environment with proper security measures and backup procedures.

n8n is an advanced, open-source workflow automation tool designed to facilitate rapid prototyping and streamlined automation of various development processes. Think of it as an open-source, self hosted alternative to Zapier. It’s intuitive, visual interface empowers developers to seamlessly connect APIs, services, and integrations without extensive coding, dramatically accelerating workflow creation and experimentation.

Moreover, n8n supports extensive AI integrations, allowing seamless incorporation of AI functionalities into workflows, unlocking opportunities for sophisticated automation and process optimisation.

Access it Securely from Anywhere Using Docker and Cloudflared

Why We Chose Docker and Cloudflared

We opted to self-host n8n using Docker for the following reasons:

• Complete control over data security and resource management.
• Scalability and ease of deployment.
• Custom integration with additional NPM modules and services such as ffmpeg.

To securely expose our n8n instance externally, we integrated Cloudflared (Cloudflare Tunnel), which:

• Ensures secure, encrypted connections without opening firewall ports directly.
• Simplifies external access via Cloudflare’s robust global infrastructure.
• Enhances security by masking the server’s IP address.

Step-by-Step Installation and Configuration

Step 1: SSH into Your Server

Wondering how to get a server? Read How to deploy an ubuntu server before continuing

ssh ubuntu@your_server_ip

Step 2: Deploy n8n with Docker

Run n8n in a Docker container using a custom environment file:

docker run -d --restart=always --env-file ./.env-n8n --name n8n -p 5678:5678 -v n8n_data:/home/node/.n8n docker.n8n.io/n8nio/n8n

Create and populate your .env-n8n file as follows:

DOMAIN_NAME=n8n.yourdomain.com
GENERIC_TIMEZONE=Europe/Berlin

Step 3: Verify and Manage Your Docker Container

Check logs:

docker logs n8n

Stop your container:

docker stop n8n

Step 4: Update Your n8n Container

Regular updates ensure security and functionality improvements:

docker stop n8n
docker rm n8n
docker run --pull always -d --restart=always --env-file ./.env-n8n --name n8n -p 5678:5678 -v n8n_data:/home/node/.n8n docker.n8n.io/n8nio/n8n

Setting Up Cloudflare Tunnel with Cloudflared

Cloudflare Tunnel (Cloudflared) securely routes traffic through Cloudflare without exposing your server IP directly.

Running Cloudflared in Docker (Recommended Method)

Execute the following command to run Cloudflared in a Docker container with host network mode:

docker run -d --restart=always --network="host" --name cloudflared cloudflare/cloudflared:latest tunnel --no-autoupdate run --token YOUR_CLOUDFLARE_TUNNEL_TOKEN

Managing Cloudflared Container

Stop and remove the Cloudflared container as needed:

docker stop cloudflared
docker rm cloudflared

Why Use Host Network Mode?

• Simplifies the setup by allowing Cloudflared to easily connect with local services.
• Eliminates the complexity of Docker’s internal networking.
• Ideal for setups managing multiple services through Cloudflare Tunnel.

Security Considerations

• Using the host network mode removes Docker’s network isolation, meaning careful consideration of the security context is required.
• Ensure your server is otherwise secure and well-monitored.

How to Access n8n

Your n8n application will be securely accessible at:

https://n8n.yourdomain.com

Application and Utility of n8n

We utilise n8n extensively for:

• Creating agile production workflows with minimal code.
• Rapid prototyping of complex automations.
• Integrating AI into existing and new processes, significantly enhancing our operational efficiency.

Getting Started with n8n

Explore these resources to jumpstart your n8n automation journey:

• Try n8n – Official Guide

Advanced Implementations

We’ve successfully transitioned various n8n workflows into full-fledged applications, including Python-based AI chatbots. Further details on such integrations:

• More posts on advanced implementations coming soon!

Taking things further with Docker Compose

While this guide provides a solid foundation for running n8n using Docker, it only scratches the surface of what’s possible. For a more advanced implementation using Docker Compose with custom NPM modules and enhanced functionality, check out our detailed guide on How to run n8n with docker compose to use custom NPM modules.

The Docker Compose setup enables you to:

• Integrate custom NPM modules like @tryfabric/martian for enhanced capabilities
• Configure complex email settings using AWS SES
• Manage persistent data storage more effectively
• Scale your automation workflows with better resource management

Using this setup, we’ve greatly enhanced our automation capabilities, boosted development efficiency, and maintained optimal security standards. Explore n8n today, and unlock a world of powerful automation possibilities!