The Complete Guide to Installing n8n on Ubuntu 22.04 VPS

The easiest way to install n8n on a newly deployed Ubuntu 22.04 VPS server is by using Docker, which requires minimal steps while ensuring a complete and secure installation. This guide provides the exact commands needed with all the latest best practices and corrections.

🚀 Step 1: Update Your System

sudo apt update && sudo apt upgrade -y

🐳 Step 2: Install Docker with Latest Official Method

sudo apt install -y apt-transport-https ca-certificates curl software-properties-common gnupg lsb-release

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

docker --version
sudo systemctl status docker

📁 Step 3: Prepare n8n Data Directory

mkdir -p ~/.n8n
sudo chown -R 1000:1000 ~/.n8n
sudo chmod -R 755 ~/.n8n

🚀 Step 4: Deploy n8n Container with Proper Configuration

docker pull n8nio/n8n

docker run -d \
  --name n8n \
  --restart unless-stopped \
  -p 5678:5678 \
  -v ~/.n8n:/home/node/.n8n \
  n8nio/n8n

🌐 Step 5: Access Your n8n Instance

Visit: http://YOUR_SERVER_IP:5678 (replace with your actual VPS IP address)

🔒 SSL Configuration for Production Use

You have two options for SSL configuration. Option 1 is strongly recommended for production environments.

🎯 Option 1: Nginx Reverse Proxy with Certbot (Recommended)

1. Install Nginx

sudo apt install -y nginx

2. Create Enhanced Nginx Configuration with WebSocket Support

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

Paste the following configuration (replace n8n.yourdomain.com with your actual domain):

# WebSocket upgrade mapping
map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

server {
    listen 80;
    server_name n8n.yourdomain.com;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header X-Content-Type-Options "nosniff" always;

    location / {
        proxy_pass http://localhost:5678;
        proxy_http_version 1.1;
        
        # WebSocket support (CRITICAL for n8n)
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        
        # Standard proxy headers
        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;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
        
        # WebSocket and performance settings
        proxy_cache_bypass $http_upgrade;
        proxy_buffering off;
        proxy_cache off;
        chunked_transfer_encoding off;
        
        # Timeouts for WebSocket connections
        proxy_connect_timeout 7d;
        proxy_send_timeout 7d;
        proxy_read_timeout 7d;
    }
}

3. Enable and Test Configuration

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

4. Install Certbot and Obtain SSL Certificate

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d n8n.yourdomain.com

5. Verify HTTPS Setup

Access your secure n8n instance at: https://n8n.yourdomain.com

6. Verify Auto-Renewal

sudo systemctl list-timers | grep certbot
sudo certbot renew --dry-run

⚙️ Option 2: Direct Docker SSL Configuration (Advanced Users)

1. Prepare Certificate Directory

mkdir -p ~/n8n/certificates
# Place your certificate files:
# ~/n8n/certificates/cert.pem (full certificate chain)
# ~/n8n/certificates/privkey.pem (private key)

2. Stop Existing Container

docker stop n8n
docker rm n8n

3. Run n8n with SSL Configuration

docker run -d \
  --name n8n \
  --restart unless-stopped \
  -p 443:5678 \
  -v ~/.n8n:/home/node/.n8n \
  -v ~/n8n/certificates:/certs \
  -e N8N_HOST="n8n.yourdomain.com" \
  -e N8N_PORT=5678 \
  -e N8N_PROTOCOL=https \
  -e WEBHOOK_URL="https://n8n.yourdomain.com/" \
  -e N8N_SSL_CERT_FILE="/certs/cert.pem" \
  -e N8N_SSL_KEY_FILE="/certs/privkey.pem" \
  n8nio/n8n

🔧 Important Configuration Notes

🛠️ Troubleshooting Common Issues

Docker Permission Issues

sudo usermod -aG docker $USER
newgrp docker
# or logout and login again

n8n Data Directory Permissions

sudo chown -R 1000:1000 ~/.n8n
sudo chmod -R 755 ~/.n8n

WebSocket Connection Issues

If workflows don’t update in real-time:

1. Verify Nginx configuration includes WebSocket upgrade mapping
2. Check that proxy headers are properly configured
3. Ensure no firewall is blocking WebSocket connections

SSL Certificate Issues

sudo certbot certificates
sudo certbot renew --dry-run

📊 Container Management Commands

# View container status
docker ps -a

# View container logs
docker logs n8n

# Follow logs in real-time
docker logs -f n8n

# Restart container
docker restart n8n

# Update n8n to latest version
docker pull n8nio/n8n
docker stop n8n
docker rm n8n
# Then run the docker run command again

# Backup n8n data
tar -czf n8n-backup-$(date +%Y%m%d).tar.gz ~/.n8n

🔐 Security Recommendations

• Use Option 1 (Nginx + Certbot) for automatic SSL certificate management
• Configure firewall rules to only allow necessary ports (22, 80, 443)
• Regular backups of the ~/.n8n directory containing workflows and credentials
• Keep Docker and n8n updated to the latest versions for security patches
• Use strong passwords and enable two-factor authentication when available
• Monitor logs regularly for any suspicious activity

📚 Additional Resources

• Official n8n Documentation
• Docker Installation Guide
• Nginx Documentation
• Certbot Documentation
• n8n Community Forum