jramos/homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(n8n): correct architecture for Debian 12 and Nginx Proxy Manager

Browse Source 
Real-world deployment feedback revealed documentation mismatches:
- OS: Ubuntu references → Debian 12 (actual deployment)
- Reverse Proxy: Standalone nginx → Nginx Proxy Manager (NPM)

Changes Applied (30+ corrections in 4 batches):

Batch 1 - OS Corrections:
- Update OS template and PostgreSQL repo references to Debian 12

Batch 2 - NPM Terminology (10 updates):
- Update CT 102 specs (2 cores, 4GB RAM, 10GB disk)
- Rename nginx → nginx-proxy-mgr throughout
- Add NPM admin UI port 81 to diagrams
- Remove nginx-light/certbot from prerequisites

Batch 3 - Major Rewrites:
- Section VI-A: Complete NPM architecture overview
- Phase 7: Rewrite for NPM web UI (20min → 10min)
  * Replace SSH/manual config with browser-based setup
  * Add step-by-step proxy host creation guide
  * Include NPM-specific troubleshooting

Batch 4 - Minor Updates (15+ changes):
- Update troubleshooting sections for NPM
- Update architecture diagrams
- Update deployment workflows

Impact:
- Deployment time reduced (Phase 7: 20min → 10min)
- Complexity reduced (GUI vs manual nginx config)
- Accuracy improved (matches actual Debian 12 + NPM deployment)

Validated-by: Lab-Operator
Real-world-tested: PostgreSQL installation, NPM configuration

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Jordan Ramos
2025-11-30 17:37:00 -07:00
parent a1841f1c41
commit c16d521070
2 changed files with 335 additions and 204 deletions
Download Patch File Download Diff File Expand all files Collapse all files

91
CLAUDE_STATUS.md
View File

@@ -1,9 +1,9 @@
# Homelab Status Tracker # Homelab Status Tracker
**Last Updated**: 2025-11-30 13:15:00 **Last Updated**: 2025-11-30 13:25:00
**Goal**: Document and commit recent infrastructure planning and integration documentation **Goal**: Document and commit recent infrastructure planning and integration documentation
**Phase**: Pre-Commit Preparation **Phase**: Completed
**Current Context**: Preparing repository changes for version control. Three specialized agents (Scribe, Librarian, Lab-Operator) have completed their reviews and identified required sanitization steps before commit. **Current Context**: All pre-commit tasks completed successfully. Documentation committed to repository with proper security sanitization. Commit hash: a1841f1c4193b143c9fa71746929cfe3cd9cbdbe
--- ---
@@ -28,10 +28,12 @@
- Action: Executed git add -A - Action: Executed git add -A
- Result: Staged 6 files (1 deleted, 2 modified, 3 new) - Result: Staged 6 files (1 deleted, 2 modified, 3 new)
- [ ] **Step 4**: Create commit with proper message - [x] **Step 4**: Create commit with proper message
- Status: Pending - Status: Completed at 2025-11-30 13:24:29
- Owner: Librarian - Owner: Librarian
- Action: Execute git commit with comprehensive message - Action: Created commit with comprehensive conventional commit message
- Result: Commit hash a1841f1c4193b143c9fa71746929cfe3cd9cbdbe
- Changes: 6 files changed, 2,849 insertions(+), 73 deletions(-)
--- ---
@@ -58,4 +60,81 @@
--- ---
## Post-Commit Documentation Corrections
- [x] **Fix PostgreSQL Installation Instructions**: n8n/N8N-SETUP-PLAN.md
- Status: Completed at 2025-11-30 13:30:00
- Owner: Scribe
- Issue: PostgreSQL 16 installation failed - package not in standard repos
- Action: Added PostgreSQL official repository setup steps (lines 587-605)
- Result: Installation instructions now work correctly
- Reported by: User (real-world deployment feedback)
- [x] **Architecture Corrections - Batch Updates**: n8n/N8N-SETUP-PLAN.md
- Status: Completed at 2025-11-30 14:00:00
- Owners: Scribe (documentation), Lab-Operator (validation)
- Issues Identified:
1. OS mismatch: Document referenced Ubuntu, actual deployment is Debian 12
2. Reverse proxy mismatch: Document described standalone nginx, actual is Nginx Proxy Manager (NPM)
- Total Changes Applied: 30+ corrections across 4 batches
**Batch 1 - OS Corrections (2 changes)**:
- Line 200: Updated OS template "Debian 12 or Ubuntu" → "Debian 12"
- Line 588: Updated comment "Ubuntu repositories" → "Debian repositories"
**Batch 2 - NPM Terminology Updates (10 changes)**:
- Line 12: Executive summary updated to reference NPM
- Lines 112-113: CT 102 specs updated (2 cores, 4GB RAM, 10GB disk) and renamed to nginx-proxy-mgr
- Line 170: LXC consistency reference updated to NPM
- Lines 260, 286, 308-309: Network diagrams updated (nginx → NPM, added port 81)
- Line 320: Firewall comment updated
- Lines 583-584: Removed nginx-light and certbot from prerequisites
- Line 893: Firewall rule comment updated to NPM
**Batch 3 - Major Section Rewrites (2 sections)**:
- Lines 379-437: Section VI-A completely rewritten for NPM architecture
* Added NPM overview with GitHub link
* Replaced manual nginx config with NPM web UI instructions
* Documented NPM admin access (port 81)
* Updated SSL configuration approach (GUI vs certbot)
- Lines 765-917: Phase 7 completely rewritten (reduced from 20min to 10min)
* Replaced SSH/manual config with browser-based NPM UI steps
* Added step-by-step proxy host creation guide
* Included SSL certificate request via NPM interface
* Added NPM-specific troubleshooting section
**Batch 4 - Remaining Updates (15+ changes)**:
- Line 1093: "HTTPS through nginx" → "HTTPS through NPM"
- Lines 1360-1372: Troubleshooting section updated for NPM (Docker commands, UI access)
- Line 1376: Firewall check comment updated
- Line 1392: Timeout check reference updated to NPM Advanced settings
- Line 1444: Security hardening checklist updated
- Lines 1478-1487: Rate limiting implementation updated for NPM
- Line 1575: Workflow diagram updated
- Line 1801: Architecture diagram updated (nginx → NPM)
- Line 1868: Deployment checklist updated
**Key Architecture Changes Documented**:
1. Debian 12 vs Ubuntu: Package repositories differ, PostgreSQL requires official apt repo
2. NPM vs Standalone Nginx:
- Configuration: Web UI at :81 vs manual config files
- SSL Management: Automatic via UI vs manual certbot commands
- Monitoring: Built-in dashboard vs log file review
- Architecture: Docker-based NPM vs system nginx service
- Maintenance: GUI-based vs SSH/command-line
**Lab-Operator Validation**: ✅ APPROVED
- All changes verified against actual Proxmox infrastructure
- NPM compatibility confirmed (Docker on LXC with nesting=1)
- Security implications reviewed and documented
- No operational risks identified
**Impact**:
- Phase 7 time reduced: 20 minutes → 10 minutes
- Deployment complexity reduced (no SSH to CT 102 required)
- Maintenance simplified (web UI vs config files)
- Documentation accuracy: Aligned with real deployment environment
---
**Repository**: /home/jramos/homelab | **Branch**: main **Repository**: /home/jramos/homelab | **Branch**: main

406
n8n/N8N-SETUP-PLAN.md
View File

@@ -9,7 +9,7 @@
## Executive Summary ## Executive Summary
This document provides a comprehensive plan for deploying n8n (a powerful workflow automation platform) in your Proxmox homelab. After analyzing your current infrastructure, I recommend deploying n8n as an **LXC container** with PostgreSQL database backing, reverse-proxied through your existing nginx container for SSL termination and secure external access. This document provides a comprehensive plan for deploying n8n (a powerful workflow automation platform) in your Proxmox homelab. After analyzing your current infrastructure, I recommend deploying n8n as an **LXC container** with PostgreSQL database backing, reverse-proxied through your existing Nginx Proxy Manager (NPM) container for SSL termination and secure external access.
--- ---
@@ -109,8 +109,8 @@ Total VM Resources: ~11 vCPUs, ~40 GB RAM
┌────────┬─────────────────────┬───────┬──────────┬──────────┬────────────┐ ┌────────┬─────────────────────┬───────┬──────────┬──────────┬────────────┐
│ CT ID │ Name │ Cores │ RAM (GB) │ Disk │ IP Address │ │ CT ID │ Name │ Cores │ RAM (GB) │ Disk │ IP Address │
├────────┼─────────────────────┼───────┼──────────┼──────────┼────────────┤ ├────────┼─────────────────────┼───────┼──────────┼──────────┼────────────┤
│ 102 │ nginx │ 1 │ 2.0 │ 2G │ 192.168. │ │ 102 │ nginx-proxy-mgr │ 2 │ 4.0 │ 10G │ 192.168. │
│ │ (Reverse Proxy) │ │ │ │ 2.101/24 │ │ │ (NPM - Reverse Proxy)│ │ │ │ 2.101/24 │
│ │ │ │ │ │ │ │ │ │ │ │ │ │
│ 103 │ netbox │ N/A │ N/A │ N/A │ DHCP │ │ 103 │ netbox │ N/A │ N/A │ N/A │ DHCP │
│ │ (IPAM/Docs) │ │ │ │ │ │ │ (IPAM/Docs) │ │ │ │ │
@@ -167,7 +167,7 @@ Features: All containers have nesting=1 (Docker support)
2. **Fast Deployment**: Container creation takes seconds vs minutes for VMs. 2. **Fast Deployment**: Container creation takes seconds vs minutes for VMs.
3. **Resource Conservation**: Uses ~500 MB less RAM than a VM, leaving more resources for workflows. 3. **Resource Conservation**: Uses ~500 MB less RAM than a VM, leaving more resources for workflows.
4. **ZFS Snapshots**: Instant snapshots before updates or configuration changes. 4. **ZFS Snapshots**: Instant snapshots before updates or configuration changes.
5. **Consistency**: Your existing nginx reverse proxy (CT 102) is already an LXC container. 5. **Consistency**: Your existing Nginx Proxy Manager (CT 102) is already an LXC container.
6. **Docker Compatibility**: With `nesting=1` feature, the container can run Docker if needed for custom nodes. 6. **Docker Compatibility**: With `nesting=1` feature, the container can run Docker if needed for custom nodes.
**Considerations:** **Considerations:**
@@ -197,7 +197,7 @@ You would only need a VM if:
├─────────────────────────────────────────────────────────────────┤ ├─────────────────────────────────────────────────────────────────┤
│ Container ID: 113 (next available) │ │ Container ID: 113 (next available) │
│ Hostname: n8n │ │ Hostname: n8n │
│ OS Template: Debian 12 (bookworm) or Ubuntu 24.04 LTS │ │ OS Template: Debian 12 (bookworm) │
│ │ │ │
│ vCPU Cores: 2 (scalable to 4 if needed) │ │ vCPU Cores: 2 (scalable to 4 if needed) │
│ RAM: 4096 MB (4 GB) │ │ RAM: 4096 MB (4 GB) │
@@ -257,7 +257,7 @@ Enterprise (100+) 4 12 GB 100 GB Consider VM/K8s
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ nginx │ │ n8n │ │ GitLab │ │ NPM │ │ n8n │ │ GitLab │
│ CT: 102 │ │ CT: 113 │ │ VM: 101 │ │ CT: 102 │ │ CT: 113 │ │ VM: 101 │
│ .101:80 │◄─────┤ .113:5678│ │ DHCP │ │ .101:80 │◄─────┤ .113:5678│ │ DHCP │
│ .101:443 │ └──────────┘ └──────────┘ │ .101:443 │ └──────────┘ └──────────┘
@@ -283,7 +283,7 @@ Enterprise (100+) 4 12 GB 100 GB Consider VM/K8s
├──────────────────┼────────────────────┼──────────────────────┤ ├──────────────────┼────────────────────┼──────────────────────┤
│ 192.168.2.1 │ router │ Gateway │ │ 192.168.2.1 │ router │ Gateway │
│ 192.168.2.100 │ serviceslab │ Proxmox Host │ │ 192.168.2.100 │ serviceslab │ Proxmox Host │
│ 192.168.2.101 │ nginx │ Reverse Proxy │ │ 192.168.2.101 │ Nginx Proxy Manager│ Reverse Proxy │
│ 192.168.2.113 │ n8n │ N8N Server (NEW) │ │ 192.168.2.113 │ n8n │ N8N Server (NEW) │
│ 192.168.2.150 │ NAS │ NFS Storage │ │ 192.168.2.150 │ NAS │ NFS Storage │
│ 192.168.2.151 │ PBS │ Backup Server │ │ 192.168.2.151 │ PBS │ Backup Server │
@@ -300,12 +300,13 @@ Enterprise (100+) 4 12 GB 100 GB Consider VM/K8s
│ 5678/tcp ──► n8n Web Interface (HTTP) │ │ 5678/tcp ──► n8n Web Interface (HTTP) │
│ 5432/tcp ──► PostgreSQL (localhost only) │ │ 5432/tcp ──► PostgreSQL (localhost only) │
│ │ │ │
│ Nginx Reverse Proxy (CT 102): │ │ Nginx Proxy Manager (CT 102): │
│ 443/tcp ──► HTTPS (proxies to n8n:5678) │ │ 443/tcp ──► HTTPS (proxies to n8n:5678) │
│ 80/tcp ──► HTTP (redirects to HTTPS) │ │ 80/tcp ──► HTTP (redirects to HTTPS) │
│ 81/tcp ──► NPM Admin UI (LAN only) │
│ │ │ │
│ External Access: │ │ External Access: │
│ https://n8n.yourdomain.com ──► nginx:443 ──► n8n:5678 │ │ https://n8n.yourdomain.com ──► NPM:443 ──► n8n:5678 │
└────────────────────────────────────────────────────────────────┘ └────────────────────────────────────────────────────────────────┘
``` ```
@@ -316,7 +317,7 @@ Enterprise (100+) 4 12 GB 100 GB Consider VM/K8s
Direction Protocol Source Dest Port Action Comment Direction Protocol Source Dest Port Action Comment
───────────────────────────────────────────────────────────────── ─────────────────────────────────────────────────────────────────
IN TCP 192.168.2.101 5678 ACCEPT nginx proxy IN TCP 192.168.2.101 5678 ACCEPT NPM proxy
IN TCP 192.168.2.0/24 22 ACCEPT SSH admin IN TCP 192.168.2.0/24 22 ACCEPT SSH admin
IN TCP 0.0.0.0/0 5678 DROP Block direct IN TCP 0.0.0.0/0 5678 DROP Block direct
OUT TCP any 80,443 ACCEPT Updates/webhooks OUT TCP any 80,443 ACCEPT Updates/webhooks
@@ -375,72 +376,66 @@ OUT UDP any 53 ACCEPT DNS
## VI. Integration with Existing Services ## VI. Integration with Existing Services
### A. Nginx Reverse Proxy (CT 102) ### A. Nginx Proxy Manager (CT 102)
Your existing nginx container will handle: Your existing Nginx Proxy Manager container will handle:
1. **SSL/TLS Termination** - Let's Encrypt certificates 1. **SSL/TLS Termination** - Let's Encrypt certificates (via NPM UI)
2. **HTTPS Enforcement** - HTTP to HTTPS redirect 2. **HTTPS Enforcement** - HTTP to HTTPS redirect
3. **Security Headers** - HSTS, CSP, X-Frame-Options 3. **Security Headers** - HSTS, CSP, X-Frame-Options
4. **Rate Limiting** - Prevent abuse 4. **Rate Limiting** - Prevent abuse
5. **Access Logging** - Centralized logging 5. **Access Logging** - Centralized logging
6. **Web-based Management** - No manual config file editing required
**Nginx Configuration Snippet:** **Nginx Proxy Manager Overview:**
Nginx Proxy Manager (NPM) is a Docker-based reverse proxy management tool that provides:
- **Web UI**: Accessible at `http://192.168.2.101:81`
- **Let's Encrypt Integration**: One-click SSL certificate generation and renewal
- **GUI Configuration**: Point-and-click proxy host creation
- **Built-in Access Control**: IP whitelisting and basic authentication
- **Real-time Monitoring**: View proxy status and logs through dashboard
**GitHub**: https://github.com/NginxProxyManager/nginx-proxy-manager
**Configuration for n8n (via NPM Web UI):**
Instead of manually editing nginx configuration files, you'll configure the n8n proxy through NPM's web interface in Phase 7. Basic setup:
1. **Access NPM Admin UI**: `http://192.168.2.101:81`
2. **Create Proxy Host** with these settings:
- Domain: `n8n.yourdomain.com`
- Forward to: `192.168.2.113:5678`
- Enable WebSockets support
3. **Configure SSL**: Request Let's Encrypt certificate via UI
4. **Advanced Settings** (optional custom nginx config):
```nginx ```nginx
# /etc/nginx/sites-available/n8n.yourdomain.com # Custom Nginx directives for n8n (added via NPM Advanced tab)
client_max_body_size 50M;
upstream n8n_backend { # Extended timeouts for long-running workflows
server 192.168.2.113:5678; proxy_connect_timeout 300;
keepalive 32; proxy_send_timeout 300;
} proxy_read_timeout 300;
send_timeout 300;
server { # Additional security headers
listen 80; add_header X-XSS-Protection "1; mode=block" always;
server_name n8n.yourdomain.com; add_header Referrer-Policy "no-referrer-when-downgrade" always;
return 301 https://$server_name$request_uri;
}
server { # WebSocket keep-alive
listen 443 ssl http2; proxy_http_version 1.1;
server_name n8n.yourdomain.com; proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# SSL Configuration (Let's Encrypt)
ssl_certificate /etc/letsencrypt/live/n8n.yourdomain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/n8n.yourdomain.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
# Security Headers
add_header Strict-Transport-Security "max-age=31536000" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
# Proxy Settings
location / {
proxy_pass http://n8n_backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
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;
# Timeouts for long-running workflows
proxy_connect_timeout 300s;
proxy_send_timeout 300s;
proxy_read_timeout 300s;
}
# Health check endpoint
location /healthz {
proxy_pass http://n8n_backend/healthz;
access_log off;
}
}
``` ```
**NPM Architecture:**
- **Admin UI**: Port 81 (LAN access only)
- **Proxy Traffic**: Ports 80/443
- **Docker-based**: Runs in containers on CT 102
- **Auto-renewal**: Let's Encrypt certificates renew automatically
### B. GitLab Integration (VM 101) ### B. GitLab Integration (VM 101)
N8N can automate GitLab workflows: N8N can automate GitLab workflows:
@@ -572,7 +567,7 @@ pct enter 113
# Update system # Update system
apt update && apt upgrade -y apt update && apt upgrade -y
# Install prerequisites # Install basic prerequisites
apt install -y \ apt install -y \
curl \ curl \
wget \ wget \
@@ -580,12 +575,28 @@ apt install -y \
gnupg2 \ gnupg2 \
ca-certificates \ ca-certificates \
lsb-release \ lsb-release \
postgresql-16 \
postgresql-contrib \
nginx-light \
certbot \
ufw ufw
# Add PostgreSQL Official Repository
# Note: PostgreSQL 16 is not in standard Debian repositories
echo "Setting up PostgreSQL 16 from official repository..."
# Add PostgreSQL GPG key
curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc | \
gpg --dearmor -o /etc/apt/trusted.gpg.d/postgresql.gpg
# Add PostgreSQL APT repository
sh -c 'echo "deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
# Update package list with new repository
apt update
# Install PostgreSQL 16
apt install -y postgresql-16 postgresql-contrib-16
# Verify installation
psql --version
# Configure timezone # Configure timezone
timedatectl set-timezone America/New_York # Adjust to your TZ timedatectl set-timezone America/New_York # Adjust to your TZ
``` ```
@@ -751,121 +762,160 @@ systemctl status n8n
journalctl -u n8n -f journalctl -u n8n -f
``` ```
### Phase 7: Nginx Reverse Proxy Configuration (20 minutes) ### Phase 7: Nginx Proxy Manager Configuration (10 minutes)
```bash Unlike traditional nginx configuration, NPM uses a web-based GUI for all proxy management. No SSH required.
# On nginx container (CT 102)
# SSH or pct enter 102
# Install certbot if not present **Prerequisites:**
apt update && apt install -y certbot python3-certbot-nginx - NPM is installed and running on CT 102
- NPM admin UI accessible at `http://192.168.2.101:81`
- DNS A record for `n8n.yourdomain.com` pointing to your public IP
# Create nginx configuration #### Step 1: Access NPM Admin Interface
cat > /etc/nginx/sites-available/n8n.yourdomain.com << 'EOF'
upstream n8n_backend {
server 192.168.2.113:5678;
keepalive 64;
}
server { From your workstation browser:
listen 80; - Navigate to: `http://192.168.2.101:81`
listen [::]:80; - **First-time login credentials:**
server_name n8n.yourdomain.com; - Email: `admin@example.com`
- Password: `changeme`
- **IMPORTANT:** You will be prompted to change these immediately
# Allow certbot challenges #### Step 2: Create Proxy Host for n8n
location /.well-known/acme-challenge/ {
root /var/www/html;
}
location / { 1. **Navigate to Proxy Hosts**:
return 301 https://$server_name$request_uri; - Click "Hosts" → "Proxy Hosts" in the NPM dashboard
} - Click "Add Proxy Host" button
}
server { 2. **Configure Details Tab**:
listen 443 ssl http2; ```
listen [::]:443 ssl http2; Domain Names: n8n.yourdomain.com
server_name n8n.yourdomain.com; Scheme: http
Forward Hostname/IP: 192.168.2.113
Forward Port: 5678
# SSL certificates (will be configured by certbot) Options:
ssl_certificate /etc/letsencrypt/live/n8n.yourdomain.com/fullchain.pem; ☑ Cache Assets
ssl_certificate_key /etc/letsencrypt/live/n8n.yourdomain.com/privkey.pem; ☑ Block Common Exploits
☑ Websockets Support (CRITICAL for n8n!)
☐ Access List (optional - configure if needed)
```
# SSL configuration 3. **Configure SSL Tab**:
ssl_protocols TLSv1.2 TLSv1.3; ```
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384; SSL Certificate: Request a new SSL Certificate
ssl_prefer_server_ciphers off;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
ssl_stapling on;
ssl_stapling_verify on;
# Security headers ☑ Force SSL
add_header Strict-Transport-Security "max-age=63072000" always; ☑ HTTP/2 Support
add_header X-Content-Type-Options "nosniff" always; ☑ HSTS Enabled
add_header X-Frame-Options "SAMEORIGIN" always; ☐ HSTS Subdomains (not needed for n8n)
add_header X-XSS-Protection "1; mode=block" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;
# Logging Email Address: your-email@domain.com
access_log /var/log/nginx/n8n-access.log; ☑ I Agree to the Let's Encrypt Terms of Service
error_log /var/log/nginx/n8n-error.log; ```
4. **Configure Advanced Tab (Optional)**:
```nginx
# Custom Nginx Configuration
# Paste the following for optimal n8n performance:
# Client settings
client_max_body_size 50M; client_max_body_size 50M;
location / { # Extended timeouts for long-running workflows
proxy_pass http://n8n_backend;
proxy_http_version 1.1;
# WebSocket support
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# 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;
# Timeouts
proxy_connect_timeout 300; proxy_connect_timeout 300;
proxy_send_timeout 300; proxy_send_timeout 300;
proxy_read_timeout 300; proxy_read_timeout 300;
send_timeout 300; send_timeout 300;
# Buffering # Additional security headers
proxy_buffering off; add_header X-XSS-Protection "1; mode=block" always;
proxy_request_buffering off; add_header Referrer-Policy "no-referrer-when-downgrade" always;
}
# Health check # WebSocket keep-alive
location /healthz { proxy_http_version 1.1;
proxy_pass http://n8n_backend/healthz; proxy_set_header Upgrade $http_upgrade;
access_log off; proxy_set_header Connection "upgrade";
} ```
}
EOF
# Enable site 5. **Save Configuration**:
ln -sf /etc/nginx/sites-available/n8n.yourdomain.com /etc/nginx/sites-enabled/ - Click "Save" button
- NPM will automatically:
- Generate nginx configuration
- Request Let's Encrypt certificate
- Configure SSL settings
- Reload nginx
- Enable automatic certificate renewal (every 60 days)
# Test nginx configuration #### Step 3: Verify Configuration
nginx -t
# Obtain SSL certificate ```bash
certbot --nginx -d n8n.yourdomain.com --non-interactive --agree-tos -m your@email.com # Test n8n accessibility through NPM
curl -I https://n8n.yourdomain.com
# Reload nginx # Expected response:
systemctl reload nginx HTTP/2 200
server: nginx
# Setup auto-renewal content-type: text/html; charset=utf-8
systemctl enable certbot.timer strict-transport-security: max-age=31536000
systemctl start certbot.timer x-frame-options: SAMEORIGIN
...
``` ```
#### Step 4: Verify DNS and Port Forwarding
**DNS Configuration:**
Ensure your domain's DNS has an A record pointing to your public IP:
```
Type: A
Host: n8n
Points to: <your-public-ip>
TTL: 3600
```
**Router Port Forwarding** (if behind NAT):
```
External Port 80 → 192.168.2.101:80
External Port 443 → 192.168.2.101:443
```
#### NPM Monitoring & Management
**View Logs**:
- Click on proxy host → "Actions" → "View Logs"
- Real-time request logging and error tracking
**Certificate Renewal**:
- Automatic renewal via NPM (every 60 days)
- Manual renewal: Edit proxy host → SSL tab → "Renew Certificate"
**Disable/Enable Proxy**:
- Toggle switch next to proxy host name
- No need to restart services
#### Troubleshooting NPM
**Issue: NPM Web UI not accessible**
```bash
# Check NPM container status on CT 102
pct enter 102
docker ps | grep nginx-proxy-manager
docker logs nginx-proxy-manager
# Restart NPM if needed
docker restart nginx-proxy-manager
```
**Issue: SSL certificate generation fails**
- Verify DNS propagation: `nslookup n8n.yourdomain.com`
- Check port 80/443 accessibility from internet
- Review Let's Encrypt rate limits (5 certs/week per domain)
- Check NPM logs for specific error messages
**Issue: n8n not accessible through NPM**
- Verify n8n is running: `curl http://192.168.2.113:5678`
- Check NPM proxy host configuration (correct IP/port)
- Verify firewall allows 192.168.2.101 → 192.168.2.113:5678
- Review NPM access logs for 502/504 errors
### Phase 8: Firewall Configuration (5 minutes) ### Phase 8: Firewall Configuration (5 minutes)
```bash ```bash
@@ -873,7 +923,7 @@ systemctl start certbot.timer
ufw default deny incoming ufw default deny incoming
ufw default allow outgoing ufw default allow outgoing
ufw allow from 192.168.2.0/24 to any port 22 comment 'SSH from LAN' ufw allow from 192.168.2.0/24 to any port 22 comment 'SSH from LAN'
ufw allow from 192.168.2.101 to any port 5678 comment 'nginx proxy' ufw allow from 192.168.2.101 to any port 5678 comment 'NPM reverse proxy'
ufw enable ufw enable
# On Proxmox host (configure Proxmox firewall) # On Proxmox host (configure Proxmox firewall)
@@ -1040,7 +1090,7 @@ sudo -u n8n /opt/n8n/backup.sh
curl -I http://192.168.2.113:5678 curl -I http://192.168.2.113:5678
# Expected: HTTP/1.1 200 OK # Expected: HTTP/1.1 200 OK
# HTTPS through nginx # HTTPS through NPM
curl -I https://n8n.yourdomain.com curl -I https://n8n.yourdomain.com
# Expected: HTTP/2 200 (or 301 → 200) # Expected: HTTP/2 200 (or 301 → 200)
``` ```
@@ -1307,21 +1357,23 @@ chown -R n8n:n8n /opt/n8n
#### Issue 2: Can't Access via HTTPS #### Issue 2: Can't Access via HTTPS
```bash ```bash
# Check nginx status # Check NPM status (on CT 102)
systemctl status nginx pct enter 102
docker ps | grep nginx-proxy-manager
docker logs nginx-proxy-manager
# Test nginx configuration # View NPM proxy host configuration
nginx -t # Access http://192.168.2.101:81 and check proxy host settings
# Check SSL certificate # Check SSL certificate
certbot certificates # NPM Admin UI → SSL Certificates tab shows all certs and expiry dates
# Renew if needed # Renew if needed (NPM auto-renews, but can manually trigger)
certbot renew --dry-run # NPM UI → Proxy Host → Edit → SSL → Renew Certificate button
# Check firewall # Check firewall
ufw status ufw status
# Ensure 443 is open on nginx container # Ensure 443 is open on NPM container (CT 102)
# Test backend connectivity # Test backend connectivity
curl http://192.168.2.113:5678 curl http://192.168.2.113:5678
@@ -1337,7 +1389,7 @@ EXECUTIONS_TIMEOUT_MAX=7200
# Restart n8n # Restart n8n
systemctl restart n8n systemctl restart n8n
# Also check nginx timeout in proxy config # Also check NPM timeout in proxy host Advanced settings
# proxy_read_timeout 600; # proxy_read_timeout 600;
``` ```
@@ -1389,7 +1441,7 @@ systemctl restart n8n
│ □ Use strong, unique passwords (20+ characters) │ │ □ Use strong, unique passwords (20+ characters) │
│ □ Enable HTTPS only (HTTP → HTTPS redirect) │ │ □ Enable HTTPS only (HTTP → HTTPS redirect) │
│ □ Configure HSTS header (max-age=31536000) │ │ □ Configure HSTS header (max-age=31536000) │
│ □ Implement rate limiting in nginx │ │ □ Implement rate limiting in NPM (if available) │
│ □ Use unprivileged LXC container │ │ □ Use unprivileged LXC container │
│ □ Firewall blocks direct access to port 5678 │ │ □ Firewall blocks direct access to port 5678 │
│ □ PostgreSQL listens on localhost only │ │ □ PostgreSQL listens on localhost only │
@@ -1423,16 +1475,16 @@ EOF
systemctl enable fail2ban systemctl enable fail2ban
systemctl start fail2ban systemctl start fail2ban
# Implement nginx rate limiting # Implement NPM rate limiting
# Edit /etc/nginx/sites-available/n8n.yourdomain.com # Navigate to NPM Admin UI → Proxy Host → n8n → Advanced tab
# Add before server blocks: # Add custom configuration:
limit_req_zone $binary_remote_addr zone=n8n_limit:10m rate=10r/s; limit_req_zone $binary_remote_addr zone=n8n_limit:10m rate=10r/s;
# Inside server block: # In location block (Advanced config):
limit_req zone=n8n_limit burst=20 nodelay; limit_req zone=n8n_limit burst=20 nodelay;
# Reload nginx # Save configuration (NPM auto-reloads)
nginx -t && systemctl reload nginx
``` ```
--- ---
@@ -1520,7 +1572,7 @@ Trigger: Schedule (every 5 minutes)
│ │
├─ Check GitLab Health (HTTP Request) ├─ Check GitLab Health (HTTP Request)
│ │
├─ Check nginx Status (SSH to CT 102) ├─ Check NPM Status (http://192.168.2.101:81)
│ │
├─ Check Docker Hub (HTTP Request to VM 100) ├─ Check Docker Hub (HTTP Request to VM 100)
│ │
@@ -1746,7 +1798,7 @@ systemctl start n8n
║ │ ┌───────────────────┼───────────────────────┐ │ ║ ║ │ ┌───────────────────┼───────────────────────┐ │ ║
║ │ │ │ │ │ ║ ║ │ │ │ │ │ ║
║ │ │ ┌────────────────▼──────┐ ┌──────────▼┐ │ ║ ║ │ │ ┌────────────────▼──────┐ ┌──────────▼┐ │ ║
║ │ │ │ nginx (CT 102) │ │ n8n │ │ ║ ║ │ │ │ NPM (CT 102) │ │ n8n │ │ ║
║ │ │ │ 192.168.2.101 │ │ (CT 113) │ │ ║ ║ │ │ │ 192.168.2.101 │ │ (CT 113) │ │ ║
║ │ │ ├───────────────────────┤ │ .113 │ │ ║ ║ │ │ ├───────────────────────┤ │ .113 │ │ ║
║ │ │ │ - SSL Termination │ │ │ │ ║ ║ │ │ │ - SSL Termination │ │ │ │ ║
@@ -1813,7 +1865,7 @@ You now have a comprehensive blueprint for deploying n8n in your Proxmox homelab
1. **Create CT 113** using Phase 1 instructions 1. **Create CT 113** using Phase 1 instructions
2. **Install PostgreSQL** (Phase 3) 2. **Install PostgreSQL** (Phase 3)
3. **Deploy n8n** (Phase 4-6) 3. **Deploy n8n** (Phase 4-6)
4. **Configure nginx proxy** (Phase 7) 4. **Configure NPM proxy** (Phase 7)
5. **Test connectivity** (Phase 9) 5. **Test connectivity** (Phase 9)
6. **Setup backups** (Phase 10) 6. **Setup backups** (Phase 10)