How to install n8n

How to Install n8n: A Comprehensive Guide

n8n is a powerful, source-available workflow automation tool that enables you to connect different applications, services, and data sources through a visual interface. Unlike some other automation platforms, n8n can be self-hosted, giving you full control over your data and workflows. This guide provides detailed instructions for the primary installation methods, including system requirements, configuration, and maintenance.

System Requirements and Prerequisites

Before installing n8n, ensure your system meets the following minimum requirements. For production environments with complex workflows, significantly higher resources are recommended.

• Operating System: Linux (Ubuntu, Debian, CentOS, etc.), macOS, or Windows (WSL2 recommended for Windows).
• CPU: 2-core processor minimum (4+ cores recommended for production).
• RAM: 4 GB minimum (8+ GB recommended for production).
• Storage: 10 GB of free disk space (SSD highly recommended).
• Software Dependencies:
  • Node.js version 18 or 20. n8n does not support Node.js version 19.
  • npm (Node Package Manager) usually installed with Node.js.
  • For database persistence, you will need PostgreSQL (recommended), MySQL, or SQLite.

Method 1: Installation Using npm (Node.js Package Manager)

This is the most straightforward method for getting n8n running on any system with Node.js installed. It is suitable for testing, development, and small-scale deployments.

Step-by-Step Installation via npm

Step 1: Install Node.js and npm
Download and install the Long-Term Support (LTS) version of Node.js from the official website. The installation includes npm. Verify the installation by opening a terminal and running:

• node --version
• npm --version

Step 2: Install n8n Globally
Use npm to install n8n as a global package. This makes the `n8n` command available system-wide.

• sudo npm install -g n8n (Linux/macOS)
• npm install -g n8n (Windows, in an elevated command prompt if necessary)

Step 3: Start n8n
Navigate to the directory where you want to run n8n (it will store data locally) and execute:

• n8n start

By default, n8n will start on http://localhost:5678. Open this address in your web browser. The first time you access it, you will be prompted to create a user account.

Basic Configuration for npm Installation

You can configure n8n using environment variables or a `.env` file in the startup directory. Key configurations include:

• Web URL: export N8N_PROTOCOL=https and export N8N_HOST=your_domain.com
• Database: export DB_TYPE=postgresdb and export DB_POSTGRESDB_DATABASE=n8n
• Security: export N8N_ENCRYPTION_KEY=your_secure_key_here

Method 2: Installation Using Docker

Docker is the recommended method for production deployments. It encapsulates n8n and its dependencies in a container, ensuring consistency and simplifying updates.

Step-by-Step Installation via Docker

Step 1: Install Docker and Docker Compose
Install Docker Engine and Docker Compose on your server. Follow the official Docker documentation for your specific operating system.

Step 2: Create a Docker Compose File
Create a directory for n8n (e.g., ~/n8n) and create a file named docker-compose.yml inside it with the following content. This example sets up n8n with a PostgreSQL database for data persistence.

version: '3.8'
services:
  n8n:
    image: n8nio/n8n
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - N8N_PROTOCOL=https
      - N8N_HOST=your_domain.com
      - N8N_PORT=5678
      - N8N_ENCRYPTION_KEY=choose_a_strong_random_key_here
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n_user
      - DB_POSTGRESDB_PASSWORD=choose_a_strong_password_here
      - N8N_METRICS=true
      - GENERIC_TIMEZONE=Europe/Berlin
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      - postgres
    networks:
      - n8n_network

  postgres:
    image: postgres:15-alpine
    container_name: n8n_postgres
    restart: unless-stopped
    environment:
      - POSTGRES_USER=n8n_user
      - POSTGRES_PASSWORD=choose_a_strong_password_here
      - POSTGRES_DB=n8n
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - n8n_network

volumes:
  n8n_data:
  postgres_data:

networks:
  n8n_network:
    driver: bridge

Step 3: Deploy the Stack
In the directory containing the docker-compose.yml file, run the following command to start n8n and PostgreSQL in detached mode:

• docker-compose up -d

n8n will be accessible on port 5678 of your server’s IP address or domain.

Method 3: Installation on Specific Platforms

Installation on Ubuntu/Debian (Native)

You can install n8n as a systemd service for automatic startup and management.

1. Install Node.js using a version manager like `nvm` or from the NodeSource repository.
2. Install n8n globally via npm: sudo npm install -g n8n
3. Create a systemd service file at /etc/systemd/system/n8n.service with proper user and environment variables.
4. Enable and start the service: sudo systemctl enable --now n8n

Installation Using Cloud Images and One-Click Apps

Many cloud providers (DigitalOcean, Hetzner, etc.) offer n8n as a one-click app or marketplace image. This method deploys a pre-configured virtual machine with n8n, a database, and often a reverse proxy (like Nginx) already installed. It is the fastest way to get a production-ready instance.

Post-Installation Configuration and Security

After installation, critical configuration steps are necessary for a secure and functional production environment.

1. Setting Up a Reverse Proxy (Nginx)

Exposing n8n directly on port 5678 is not recommended. Use Nginx or Apache as a reverse proxy to handle SSL termination and routing.

Example Nginx server block configuration:

server {
    server_name your_domain.com;

    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;
    }

    listen 443 ssl;
    ssl_certificate /path/to/your/fullchain.pem;
    ssl_certificate_key /path/to/your/privkey.pem;
}

2. Database Configuration for Persistence

Using SQLite (default in npm install) is only for testing. For production, use PostgreSQL. The key environment variables for PostgreSQL configuration are listed in the Docker Compose example above. Ensure you run migrations if upgrading n8n versions.

3. Essential Environment Variables

Variable	Purpose	Example
N8N_ENCRYPTION_KEY	Encrypts credentials in the database. Mandatory and must be consistent.	my-secret-encryption-key-32-chars
N8N_PROTOCOL & N8N_HOST	Sets the base URL for webhook callbacks.	https://automate.yourcompany.com
EXECUTIONS_DATA_PRUNE	Automatically deletes old execution data to save space.	true
EXECUTIONS_DATA_MAX_AGE	Sets the max age (in hours) for execution data.	168 (1 week)
WEBHOOK_URL	Overrides the public webhook URL if different from N8N_HOST.	https://webhooks.yourcompany.com

Updating and Maintaining n8n

Regular updates are crucial for security and new features.

• npm: Run sudo npm update -g n8n and restart the process.
• Docker: In your compose directory, run docker-compose pull n8n, then docker-compose up -d.
• Backup: Regularly back up your database (PostgreSQL dumps) and the .n8n directory (contains credentials, workflows JSON).

Frequently Asked Questions (FAQ)

Q1: What is the default port for n8n, and how do I change it?

The default port is 5678. You can change it by setting the environment variable N8N_PORT (e.g., export N8N_PORT=8080) or by using the command-line flag --port=8080 when starting n8n.

Q2: How do I reset the admin password if I lose it?

If you have shell access to the server running n8n, you can generate a new password hash. First, navigate to the n8n installation directory, then run: node -e "console.log(require('bcryptjs').hashSync('your-new-password', 10))". Copy the output hash and update the `user` table in your database, setting the `password` field for your user to this new hash.

Q3: Can I run n8n behind a corporate proxy?

Yes. Set the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables in the n8n process environment. In Docker, add these variables to the `environment` section of your compose file.

Q4: What is the difference between n8n.cloud and self-hosted n8n?

n8n.cloud is the managed, paid SaaS version hosted by the n8n team. It handles updates, infrastructure, and scaling. Self-hosted n8n is free (under the source-available license) and requires you to manage the server, updates, security, and backups, but offers full data control and customization.

Q5: Why are my webhooks not working after deploying behind a reverse proxy?

This is often due to incorrect URL configuration. Ensure the N8N_HOST and N8N_PROTOCOL environment variables are set to the external, public URL that you use to access n8n (e.g., https://automate.yourdomain.com). n8n uses this to construct the webhook URL it provides to external services.

Q6: How can I improve performance for many workflows?

Consider the following:

• Enable workflow pruning (EXECUTIONS_DATA_PRUNE).
• Use a dedicated PostgreSQL database.
• Increase server resources (CPU/RAM).
• Use the «Main» process mode for heavy workflows and the «Webhook» process mode for latency-sensitive triggers.
• Scale horizontally using multiple n8n workers (enterprise feature).

Conclusion

Installing n8n can range from a simple npm command for local experimentation to a sophisticated Docker-based deployment for enterprise automation. The key to a successful production installation lies in proper configuration: using a reverse proxy with SSL, setting a strong encryption key, configuring a persistent PostgreSQL database, and implementing a strategy for updates and backups. By following the detailed steps for your chosen method and adhering to the security recommendations, you can establish a robust and scalable workflow automation platform under your complete control.