How to run n8n as a background service?

quote from here

To run n8n as a background service, you need to set up a process manager that will manage the n8n application, ensuring it runs continuously in the background, restarts after failures, and starts automatically after system reboots. The most common methods include using systemd (on Linux), PM2 (cross-platform), or Docker. Each method provides different advantages in terms of logging, monitoring, and management capabilities.

 

Step 1: Understanding the Options for Running n8n as a Background Service

 

Before setting up n8n as a background service, it's important to understand the available options:

1. systemd: The default service manager for many Linux distributions.
2. PM2: A popular Node.js process manager that works across platforms.
3. Docker: Containerization platform that can run n8n in an isolated environment.
4. Windows Services: For Windows users, native service management.

We'll cover each of these methods in detail below.

 

Step 2: Prerequisites

 

Before proceeding, ensure you have:

• n8n installed on your system
• Administrator/root privileges to set up system services
• Basic command-line knowledge

If you haven't installed n8n yet, you can do so using npm:

npm install n8n -g

 

Step 3: Using systemd on Linux

 

systemd is the most common service manager for modern Linux distributions (Ubuntu, Debian, CentOS, etc.).

Step 3.1: Create a systemd service file

Create a new service file:

sudo nano /etc/systemd/system/n8n.service

Step 3.2: Add service configuration

Add the following content to the file, adjusting paths and user as needed:

[Unit]
Description=n8n workflow automation
After=network.target

[Service]
Type=simple
User=YOUR\_USER # Replace with your username
WorkingDirectory=/home/YOUR\_USER # Replace with your home directory
ExecStart=/usr/bin/npm start
Restart=on-failure
RestartSec=10
Environment=N8N_ENCRYPTION_KEY=YOUR_ENCRYPTION_KEY # Optional but recommended
Environment=NODE\_ENV=production

[Install]
WantedBy=multi-user.target

Step 3.3: Enable and start the service

Reload systemd to recognize the new service:

sudo systemctl daemon-reload

Enable the service to start on boot:

sudo systemctl enable n8n

Start the service:

sudo systemctl start n8n

Step 3.4: Check service status

Verify that the service is running correctly:

sudo systemctl status n8n

Step 3.5: Managing the service

To stop the service:

sudo systemctl stop n8n

To restart the service:

sudo systemctl restart n8n

To view logs:

sudo journalctl -u n8n -f

 

Step 4: Using PM2 (Cross-Platform)

 

PM2 is a process manager for Node.js applications that works on all major platforms, including Linux, macOS, and Windows.

Step 4.1: Install PM2

First, install PM2 globally:

npm install pm2 -g

Step 4.2: Create an ecosystem file (optional but recommended)

Create a PM2 ecosystem file to configure n8n:

nano ecosystem.config.js

Add the following content:

module.exports = {
  apps: [{
    name: 'n8n',
    script: 'n8n',
    args: 'start',
    env: {
      NODE\_ENV: 'production',
      N8N_ENCRYPTION_KEY: 'your-encryption-key', // Replace with your key
      // Add other environment variables as needed
    },
    exec\_mode: 'fork',
    instances: 1,
    autorestart: true,
    watch: false,
    max_memory_restart: '1G'
  }]
};

Step 4.3: Start n8n with PM2

If you're using the ecosystem file:

pm2 start ecosystem.config.js

Or start n8n directly:

pm2 start n8n -- start

Step 4.4: Set PM2 to start on boot

To make n8n start automatically when your system boots:

pm2 startup

This will output a command that you should copy and run. After running that command, save the current PM2 configuration:

pm2 save

Step 4.5: Managing n8n with PM2

Check status:

pm2 status

View logs:

pm2 logs n8n

Restart n8n:

pm2 restart n8n

Stop n8n:

pm2 stop n8n

Delete n8n from PM2:

pm2 delete n8n

 

Step 5: Using Docker

 

Docker provides an isolated environment for n8n to run with all dependencies included.

Step 5.1: Install Docker

If you don't have Docker installed, follow the official instructions for your platform:
https://docs.docker.com/get-docker/

Step 5.2: Create a Docker Compose file

Create a file named docker-compose.yml:

nano docker-compose.yml

Add the following content:

version: '3'

services:
  n8n:
    image: n8nio/n8n
    restart: always
    ports:
    - "5678:5678"
    volumes:
    - ~/.n8n:/home/node/.n8n
    environment:
    - N8N_ENCRYPTION_KEY=your-encryption-key # Replace with your key
    - NODE\_ENV=production
      # Add other environment variables as needed

Step 5.3: Start n8n with Docker Compose

Run n8n in the background:

docker-compose up -d

Step 5.4: Enable auto-start on boot

On most Linux distributions, Docker is configured to start on boot by default. If you need to enable this:

sudo systemctl enable docker

Step 5.5: Managing n8n in Docker

Check status:

docker-compose ps

View logs:

docker-compose logs -f

Stop n8n:

docker-compose down

Restart n8n:

docker-compose restart

 

Step 6: Running n8n as a Windows Service

 

For Windows users, you can use tools like NSSM (Non-Sucking Service Manager) to run n8n as a Windows service.

Step 6.1: Install NSSM

Download NSSM from: https://nssm.cc/download

Extract the zip file and place the appropriate executable (nssm.exe from the win32 or win64 folder) in a permanent location, such as C:\tools\nssm.exe.

Step 6.2: Add the NSSM directory to your PATH

This makes it easier to run NSSM from anywhere. To do this:

1. Open the Start menu and search for "Environment Variables"

2. Select "Edit the system environment variables"

3. Click the "Environment Variables" button

4. Under "System variables", find "Path" and click "Edit"

5. Click "New" and add the path to the directory containing nssm.exe (e.g., C:\tools)

6. Click "OK" on all dialogs to save changes

Step 6.3: Create a batch file to start n8n

Create a file named start-n8n.bat:

@echo off
set N8N_ENCRYPTION_KEY=your-encryption-key
set NODE\_ENV=production
n8n start

Save this file in a permanent location, such as C:\scripts\start-n8n.bat.

Step 6.4: Create the Windows service using NSSM

Open Command Prompt as Administrator and run:

nssm install n8n

This will open a GUI where you can configure the service:

• In the "Application" tab:

• Path: Enter the path to node.exe (usually C:\Program Files\nodejs\node.exe)

• Startup directory: The directory where your batch file is located

• Arguments: The full path to your batch file

• In the "Details" tab:

• Display name: n8n

• Description: n8n workflow automation service

• Startup type: Automatic

Click "Install service".

Step 6.5: Start and manage the service

Start the service:

nssm start n8n

Check status:

sc query n8n

Stop the service:

nssm stop n8n

Remove the service:

nssm remove n8n

 

Step 7: Additional Configuration Options

 

Regardless of which method you choose, you might want to configure additional n8n settings.

Step 7.1: Common environment variables

You can add these environment variables to any of the setup methods above:

N8N_ENCRYPTION_KEY=your-secure-key  # Required for production
N8N\_PORT=5678                       # Default port
N8N\_PROTOCOL=http                   # or https
N8N\_HOST=localhost                  # Host name
N8N\_PATH=/                          # Base path
N8N_EDITOR_BASE\_URL=http://localhost:5678  # URL for the editor
DB\_TYPE=sqlite                      # Database type (sqlite, postgresdb, mysqldb, mariadb)
DB\_PATH=~/.n8n/database.sqlite      # Path for SQLite database
N8N_LOG_LEVEL=info                  # Log level (error, warn, info, verbose, debug)

Step 7.2: Setting up a database

For production use, it's recommended to use a proper database instead of SQLite:

For PostgreSQL:

DB\_TYPE=postgresdb
DB_POSTGRESDB_HOST=localhost
DB_POSTGRESDB_PORT=5432
DB_POSTGRESDB_DATABASE=n8n
DB_POSTGRESDB_USER=n8n\_user
DB_POSTGRESDB_PASSWORD=password

For MySQL/MariaDB:

DB\_TYPE=mysqldb  # or mariadb
DB_MYSQLDB_HOST=localhost
DB_MYSQLDB_PORT=3306
DB_MYSQLDB_DATABASE=n8n
DB_MYSQLDB_USER=n8n\_user
DB_MYSQLDB_PASSWORD=password

 

Step 8: Setting Up a Reverse Proxy (Optional)

 

For production environments, it's recommended to set up a reverse proxy like Nginx or Apache to handle HTTPS and expose n8n securely.

Step 8.1: Example Nginx configuration

Install Nginx:

sudo apt update
sudo apt install nginx

Create a configuration file:

sudo nano /etc/nginx/sites-available/n8n

Add this configuration:

server {
    listen 80;
    server\_name your-domain.com;

    # Redirect HTTP to HTTPS
    return 301 https://$host$request\_uri;
}

server {
    listen 443 ssl;
    server\_name your-domain.com;

    # SSL Configuration
    ssl\_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    ssl\_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server\_ciphers on;
    ssl\_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384;

    # Proxy Configuration
    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;
        
        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http\_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/n8n /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Step 8.2: Securing with Let's Encrypt

Install Certbot:

sudo apt install certbot python3-certbot-nginx

Obtain a certificate:

sudo certbot --nginx -d your-domain.com

 

Step 9: Monitoring and Maintaining Your n8n Service

 

Step 9.1: Regular backups

Set up regular backups of your n8n data:

# For SQLite database
cp ~/.n8n/database.sqlite ~/backups/n8n\_$(date +%Y%m%d).sqlite

# For Docker volumes
docker run --rm -v n8n\_data:/source -v ~/backups:/backup ubuntu tar -czf /backup/n8n-backup-$(date +%Y%m%d).tar.gz /source

Step 9.2: Monitoring health

Set up monitoring to check if n8n is responding:

# Simple curl check
curl -s -o /dev/null -w "%{http\_code}" http://localhost:5678

This can be added to a cron job that sends alerts if the status code isn't 200.

Step 9.3: Log rotation

For PM2, enable log rotation:

pm2 install pm2-logrotate
pm2 set pm2-logrotate:max\_size 10M
pm2 set pm2-logrotate:retain 5

For systemd, configure logrotate:

sudo nano /etc/logrotate.d/n8n

Add the content:

/var/log/n8n/\*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 640 root adm
}

 

Step 10: Troubleshooting Common Issues

 

Step 10.1: Service won't start

Check for port conflicts:

sudo netstat -tuln | grep 5678

Check logs for errors:

# For systemd
sudo journalctl -u n8n -n 100

# For PM2
pm2 logs n8n --lines 100

# For Docker
docker-compose logs --tail 100

Step 10.2: Permission issues

Ensure proper ownership of n8n directories:

sudo chown -R your_user:your_user ~/.n8n

Step 10.3: Database connection issues

Test database connectivity:

# For PostgreSQL
psql -h localhost -U n8n\_user -d n8n

# For MySQL/MariaDB
mysql -h localhost -u n8n\_user -p n8n

Step 10.4: Memory issues

If n8n crashes due to memory issues, you can increase the memory limit:

# For Node.js
NODE\_OPTIONS="--max-old-space-size=4096" n8n start

# In PM2 ecosystem file
env: {
  NODE\_OPTIONS: "--max-old-space-size=4096"
}

 

Step 11: Updating n8n

 

Step 11.1: Update with npm

For installations using npm:

npm update -g n8n
sudo systemctl restart n8n  # If using systemd
pm2 restart n8n             # If using PM2

Step 11.2: Update with Docker

For Docker installations:

docker-compose pull
docker-compose down
docker-compose up -d

Step 11.3: Check version

Verify the update was successful:

n8n --version

 

Conclusion

 

You now have a comprehensive guide for running n8n as a background service using various methods. Each approach has its advantages:

• systemd: Ideal for Linux servers with tight system integration
• PM2: Great for cross-platform deployment with detailed monitoring
• Docker: Perfect for isolated, consistent environments
• Windows Service: The best native solution for Windows servers

Choose the method that best fits your environment and requirements. Remember to regularly back up your data, monitor the service health, and keep your n8n installation updated to benefit from the latest features and security improvements.