Nginx

Nginx High-Performance Reverse Proxy AI Skill Guide (Claude)

Overview & Engine Architecture

Nginx is the world's most widely deployed high-performance HTTP server, reverse proxy, mail proxy, and generic TCP/UDP proxy. Claude operates as a Principal Infrastructure Architect and Site Reliability Engineer (SRE), specializing in asynchronous event-driven architecture (epoll/kqueue), hardened SSL/TLS termination (TLS 1.3, OCSP Stapling, HSTS), dynamic upstream load balancing (least_conn, ip_hash), and zero-downtime hot reloading (nginx -s reload).

Nginx Master-Worker Process Architecture

┌─────────────────────────────────────────────────────────────┐
│                 Nginx Process & Event Model                 │
│                                                             │
│  Master Process (Root privileges, parses config, binds ports)│
│  └── Spawns & Supervises Worker Processes                   │
│                                                             │
│  Worker Processes (Unprivileged `nginx`/`www-data` user)    │
│  ├── Event Loop (`epoll` Linux / `kqueue` BSD/macOS)        │
│  ├── Non-blocking Asynchronous Socket Multiplexing          │
│  ├── Microsecond Static Asset Disk Cache Engine             │
│  └── Upstream Connection Pool (Keepalive HTTP/1.1 to App)   │
└─────────────────────────────────────────────────────────────┘

Operational Capabilities & Agent Directives

1. Hardened Configuration Generation: Author clean, production-grade nginx.conf files incorporating modern security headers (HSTS, Content-Security-Policy, X-Content-Type-Options, X-Frame-Options), rate limiting zones, and Gzip compression.
2. Reverse Proxying & WebSocket Upgrades: Configure proxy_pass blocks with proper header forwarding (X-Forwarded-For, X-Forwarded-Proto, Host) and bidirectional WebSocket upgrade blocks (Upgrade, Connection "upgrade").
3. Gateway Error Remediation (502 / 504 / 413): Rapidly identify root causes behind upstream connection drops, SELinux socket blocks, proxy read timeouts, and body payload truncation.
4. SSL/TLS & Automated Certbot Integration: Configure ACES/Let's Encrypt automated certificate renewals, intermediate certificate bundle assembly, and modern Mozilla intermediate cipher suites.

Production Configuration Recipe: Hardened SSL Reverse Proxy & WebSockets

Save this configuration as /etc/nginx/sites-available/api_gateway.conf:

# Rate Limiting Zone: 10MB memory zone, max 20 requests/sec per IP
limit_req_zone $binary_remote_addr zone=api_rate_limit:10m rate=20r/s;

# Upstream Backend Cluster with Keepalive
upstream backend_api_cluster {
    least_conn;
    server 127.0.0.1:8001 max_fails=3 fail_timeout=10s;
    server 127.0.0.1:8002 max_fails=3 fail_timeout=10s;
    keepalive 32;
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name api.enterprise.io;
    return 301 https://$host$request_uri;
}

# Production HTTPS Server Block
server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name api.enterprise.io;

    # SSL Certificates (Full Chain + Private Key)
    ssl_certificate /etc/letsencrypt/live/api.enterprise.io/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.enterprise.io/privkey.pem;

    # Modern TLS Security & Ciphers
    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_prefer_server_ciphers off;
    ssl_session_timeout 1d;
    ssl_session_cache shared:SSL:10m;
    ssl_session_tickets off;

    # OCSP Stapling
    ssl_stapling on;
    ssl_stapling_verify on;
    resolver 1.1.1.1 8.8.8.8 valid=300s;
    resolver_timeout 5s;

    # Security Headers
    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
    add_header X-Frame-Options "DENY" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;

    # Payload & Buffer Limits
    client_max_body_size 50M;
    client_body_buffer_size 128k;

    # Gzip Compression
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml;

    # API & WebSocket Reverse Proxy
    location / {
        limit_req zone=api_rate_limit burst=10 nodelay;

        proxy_pass http://backend_api_cluster;
        proxy_http_version 1.1;

        # WebSocket & Connection Upgrade Headers
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Standard Client Forwarding 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;

        # Upstream Timeouts (e.g. For long-running AI / streaming requests)
        proxy_connect_timeout 60s;
        proxy_send_timeout 120s;
        proxy_read_timeout 120s;
    }
}

Technical Troubleshooting Matrix

Command Line Syntax & Server Management

# 1. Test Configuration Syntax (Crucial before any reload)
nginx -t

# 2. Zero-Downtime Hot Reload
nginx -s reload

# 3. Inspect Live Error and Access Logs
tail -f /var/log/nginx/error.log
tail -f /var/log/nginx/access.log

# 4. Generate Free Let's Encrypt SSL Certificate via Certbot
certbot --nginx -d api.enterprise.io

Essential File & Directory Paths

• Master Configuration: /etc/nginx/nginx.conf
• Site Configurations: /etc/nginx/sites-available/ and /etc/nginx/sites-enabled/ (Debian/Ubuntu) or /etc/nginx/conf.d/*.conf (RHEL/Alpine)
• Log Files: /var/log/nginx/access.log and /var/log/nginx/error.log
• Windows Nginx Path: C:\nginx\ (Execute nginx.exe -s reload)

Agent Operational Directive

MANDATORY: Always run nginx -t to validate syntax before executing nginx -s reload or restarting the system daemon. Never commit plain HTTP listeners without automatic 301 redirection to HTTPS in production environments.