# How to Run n8n as a Background Service

- Tool: n8n
- Difficulty: Beginner
- Time required: 15-20 minutes
- Compatibility: n8n 1.0+ (self-hosted on Linux, macOS, or Docker)
- Last updated: March 2026

## TL;DR

To run n8n as a background service, create a systemd unit file on Linux, use PM2 as a Node.js process manager, or deploy with Docker using a restart policy. All three methods ensure n8n starts automatically on boot, restarts after crashes, and runs without requiring an open terminal session.

## Running n8n Persistently as a Background Service

By default, running n8n from the command line ties it to your terminal session — if you close the terminal or SSH connection, n8n stops. For production use, you need n8n to run as a background service that starts on boot, survives disconnections, and restarts automatically after crashes. This tutorial covers three approaches: systemd on Linux, PM2 for any Node.js environment, and Docker with restart policies.

## Before you start

- n8n installed on your server (via npm, Docker, or binary)
- Root or sudo access (for systemd)
- Node.js 18+ and npm installed (for PM2 method)

## Step-by-step guide

### 1. Option A: Create a systemd service file for n8n

Systemd is the standard service manager on most Linux distributions (Ubuntu, Debian, CentOS, RHEL). Create a service unit file that tells systemd how to start, stop, and restart n8n. The file defines the user to run n8n as, environment variables, and the restart policy. After creating the file, enable the service so it starts on boot, then start it immediately. This is the most robust option for Linux servers.

```
# Create the service file
sudo nano /etc/systemd/system/n8n.service

# Paste the following content:
[Unit]
Description=n8n Workflow Automation
After=network.target

[Service]
Type=simple
User=n8n
WorkingDirectory=/home/n8n
ExecStart=/usr/bin/n8n start
Restart=always
RestartSec=10
Environment=N8N_PORT=5678
Environment=N8N_ENCRYPTION_KEY=your-encryption-key
Environment=WEBHOOK_URL=https://n8n.yourdomain.com/
Environment=GENERIC_TIMEZONE=America/New_York
Environment=DB_TYPE=postgresdb
Environment=DB_POSTGRESDB_HOST=localhost
Environment=DB_POSTGRESDB_PORT=5432
Environment=DB_POSTGRESDB_DATABASE=n8n
Environment=DB_POSTGRESDB_USER=n8n
Environment=DB_POSTGRESDB_PASSWORD=your-db-password

[Install]
WantedBy=multi-user.target
```

**Expected result:** The service file is created at /etc/systemd/system/n8n.service.

### 2. Enable and start the systemd service

After creating the service file, reload systemd to pick up the new configuration, enable the service to start on boot, and start it immediately. Verify the service is running by checking its status. The logs are available through journalctl. If the service fails to start, the logs will show the exact error message.

```
# 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 now
sudo systemctl start n8n

# Check the status
sudo systemctl status n8n

# View logs
journalctl -u n8n -f
```

**Expected result:** The n8n service is active and running. It will automatically start on server reboot.

### 3. Option B: Use PM2 to manage n8n as a background process

PM2 is a production process manager for Node.js applications. It works on Linux and macOS and does not require root access. Install PM2 globally, then start n8n with PM2. Configure PM2 to start on boot with the startup command. PM2 automatically restarts n8n if it crashes, logs output to files, and provides a monitoring dashboard.

```
# Install PM2 globally
npm install -g pm2

# Start n8n with PM2
N8N_ENCRYPTION_KEY=your-encryption-key \
WEBHOOK_URL=https://n8n.yourdomain.com/ \
pm2 start n8n -- start

# Or use an ecosystem file for complex configuration
# (see complete_code section below)

# Save the PM2 process list
pm2 save

# Generate startup script (run the command it outputs)
pm2 startup

# Check status
pm2 status

# View logs
pm2 logs n8n
```

**Expected result:** n8n is running as a PM2-managed process that automatically restarts on crash and starts on boot.

### 4. Option C: Run n8n in Docker with a restart policy

Docker provides the simplest setup for running n8n as a background service. The --restart=always flag tells Docker to restart the n8n container if it crashes, and to start it when the Docker daemon starts (which is typically on boot). Use Docker Compose for easier configuration management. The container runs in detached mode (-d), so it does not require a terminal session.

```
# Single Docker command
docker run -d \
  --name n8n \
  --restart=always \
  -p 5678:5678 \
  -e N8N_ENCRYPTION_KEY=your-encryption-key \
  -e WEBHOOK_URL=https://n8n.yourdomain.com/ \
  -e GENERIC_TIMEZONE=America/New_York \
  -v n8n_data:/home/node/.n8n \
  n8nio/n8n

# Check it is running
docker ps | grep n8n

# View logs
docker logs n8n -f
```

**Expected result:** n8n runs in a Docker container that restarts automatically after crashes and on server reboot.

### 5. Verify the background service is working correctly

After setting up any of the three methods, verify that n8n is running by opening the web UI in your browser at http://your-server-ip:5678. Then test the auto-restart by stopping and starting the service or simulating a crash. For systemd, run sudo systemctl restart n8n. For PM2, run pm2 restart n8n. For Docker, run docker restart n8n. Check that n8n becomes available again within 10-30 seconds. Finally, test boot persistence by rebooting the server and confirming n8n starts automatically.

```
# Test auto-restart (all methods)
# Systemd
sudo systemctl restart n8n && systemctl status n8n

# PM2
pm2 restart n8n && pm2 status

# Docker
docker restart n8n && docker ps | grep n8n

# Test boot persistence (reboot and check)
sudo reboot
# After reboot, SSH back in and verify:
systemctl status n8n   # or
pm2 status             # or
docker ps | grep n8n
```

**Expected result:** n8n restarts automatically and is accessible in the browser after both a restart and a full server reboot.

## Complete code example

File: `ecosystem.config.js`

```javascript
// PM2 Ecosystem File for n8n
// Save as ecosystem.config.js and run: pm2 start ecosystem.config.js

module.exports = {
  apps: [
    {
      name: 'n8n',
      script: 'n8n',
      args: 'start',
      interpreter: 'none',
      autorestart: true,
      watch: false,
      max_restarts: 10,
      restart_delay: 5000,
      max_memory_restart: '1G',
      env: {
        N8N_PORT: 5678,
        N8N_ENCRYPTION_KEY: 'your-encryption-key',
        WEBHOOK_URL: 'https://n8n.yourdomain.com/',
        GENERIC_TIMEZONE: 'America/New_York',
        N8N_LOG_LEVEL: 'info',
        EXECUTIONS_DATA_PRUNE: 'true',
        EXECUTIONS_DATA_MAX_AGE: '168',
        EXECUTIONS_DATA_SAVE_ON_ERROR: 'all',
        EXECUTIONS_DATA_SAVE_ON_SUCCESS: 'none',
        DB_TYPE: 'postgresdb',
        DB_POSTGRESDB_HOST: 'localhost',
        DB_POSTGRESDB_PORT: '5432',
        DB_POSTGRESDB_DATABASE: 'n8n',
        DB_POSTGRESDB_USER: 'n8n',
        DB_POSTGRESDB_PASSWORD: 'your-db-password'
      },
      env_production: {
        NODE_ENV: 'production',
        N8N_LOG_LEVEL: 'warn'
      }
    }
  ]
};

// Usage:
// pm2 start ecosystem.config.js
// pm2 start ecosystem.config.js --env production
// pm2 save
// pm2 startup
```

## Common mistakes

- **Running n8n with nohup or screen instead of a proper service manager** — undefined Fix: Use systemd, PM2, or Docker. nohup and screen do not restart on crash or start on boot reliably.
- **Running n8n as root, creating security risks** — undefined Fix: Create a dedicated n8n user and run the service as that user. Set User=n8n in the systemd file.
- **Setting environment variables in .bashrc instead of the service file** — undefined Fix: Service managers do not read shell profiles. Set environment variables in the systemd unit file, PM2 ecosystem file, or Docker Compose file.
- **Forgetting to run pm2 save after starting n8n, causing PM2 to forget the process on reboot** — undefined Fix: Always run pm2 save after starting or updating PM2 processes, and run pm2 startup to generate the boot script.

## Best practices

- Always use a restart policy (Restart=always, --restart=always, or autorestart: true) to recover from crashes
- Create a dedicated non-root user for running n8n to improve security
- Store environment variables in the service configuration, not in shell profiles
- Use PostgreSQL instead of SQLite for production deployments with multiple workflows
- Set a memory limit (max_memory_restart in PM2 or Docker memory limits) to prevent n8n from consuming all server RAM
- Configure log rotation to prevent log files from filling the disk
- Monitor the service with health checks — curl the n8n health endpoint periodically

## Frequently asked questions

### Which method is best: systemd, PM2, or Docker?

Docker is the simplest to set up and the most portable. Systemd is the most native option for Linux servers. PM2 works well if you are already using Node.js and want a unified process manager. For production, Docker or systemd are recommended over PM2.

### How do I check if n8n is running as a background service?

For systemd: systemctl status n8n. For PM2: pm2 status. For Docker: docker ps | grep n8n. Each command shows whether n8n is running, how long it has been up, and its process ID.

### Can I run n8n as a background service on macOS?

macOS does not use systemd. Use PM2 or Docker instead. PM2 works natively on macOS and can be configured to start on login with pm2 startup. Docker Desktop for macOS also supports restart policies.

### How do I update n8n when it is running as a service?

For npm installs: stop the service, run npm install -g n8n@latest, then start the service. For Docker: pull the latest image with docker pull n8nio/n8n, stop the container, and start it again. For Docker Compose: run docker compose pull && docker compose up -d.

### What happens to running workflows when the service restarts?

Active workflow executions are interrupted. Scheduled triggers are re-registered after restart. If you have Save Execution Progress enabled, the partial data is available in the Executions tab.

### Can RapidDev help me set up a production n8n deployment?

Yes, RapidDev can configure a production-grade n8n deployment with systemd or Docker, PostgreSQL, HTTPS, automated backups, and monitoring — ensuring your automation platform is reliable and maintainable.

---

Source: https://www.rapidevelopers.com/n8n-tutorial/how-to-run-n8n-as-a-background-service
© RapidDev — https://www.rapidevelopers.com/n8n-tutorial/how-to-run-n8n-as-a-background-service