How to run n8n with docker compose to use custom NPM modules

30 March 2025 By  Eugene Evenwel Tooling

Introduction

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 <[email protected]>

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.