Nginx

Nginx Configuration

Nginx Configuration Nginx is a high-performance web server and reverse proxy. Its event-driven architecture makes it highly efficient for serving static content…

Nginx Configuration

Nginx is a high-performance web server and reverse proxy. Its event-driven architecture makes it highly efficient for serving static content, terminating SSL, and proxying to application servers.

Core Config Structure

# /etc/nginx/nginx.conf — main config
user nginx;
worker_processes auto;           # one worker per CPU core
pid /var/run/nginx.pid;

events {
    worker_connections 1024;     # max simultaneous connections per worker
    multi_accept on;             # accept all pending connections at once
    use epoll;                   # Linux: efficient event notification
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    # Logging format
    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" "$http_user_agent"';
    access_log /var/log/nginx/access.log main;
    error_log  /var/log/nginx/error.log warn;

    # Performance
    sendfile        on;       # zero-copy file transfer
    tcp_nopush      on;       # batch send headers
    tcp_nodelay     on;       # disable Nagle algorithm
    keepalive_timeout 65;     # keep connections open for 65s

    # Gzip compression
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types
        text/plain text/css text/xml application/json
        application/javascript application/rss+xml
        application/atom+xml image/svg+xml;

    # Include site configs
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

Server Blocks & Location Matching

# Location matching priority (highest to lowest):
# 1. = exact match          location = /favicon.ico
# 2. ^~ prefix (no regex)   location ^~ /images/
# 3. ~ case-sensitive regex  location ~ \.php$
# 4. ~* case-insensitive rx  location ~* \.(jpg|png|gif)$
# 5. / prefix (fallback)     location /

server {
    listen 80;
    server_name example.com www.example.com;
    root /var/www/html;
    index index.html index.htm;

    # Exact match — served instantly, no further checks
    location = /favicon.ico {
        access_log off;
        log_not_found off;
    }

    # Static assets — long cache, served directly
    location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    # PHP processing via FastCGI
    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    # SPA fallback — serve index.html for all unmatched routes
    location / {
        try_files $uri $uri/ /index.html;
    }

    # Custom error pages
    error_page 404 /404.html;
    error_page 500 502 503 504 /50x.html;
    location = /50x.html {
        root /usr/share/nginx/html;
    }
}

SSL & HTTPS with Let's Encrypt

# Force HTTP -> HTTPS redirect
server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name example.com www.example.com;

    # SSL certificate (from Let's Encrypt / certbot)
    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    # Modern SSL settings
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;    # let client choose (TLS 1.3)
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;
    ssl_session_tickets off;          # forward secrecy

    # OCSP stapling (faster cert validation)
    ssl_stapling on;
    ssl_stapling_verify on;
    resolver 8.8.8.8 8.8.4.4 valid=300s;

    # Security headers
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
    add_header X-Frame-Options DENY always;
    add_header X-Content-Type-Options nosniff always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
    add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'" always;

    location / {
        root /var/www/html;
        try_files $uri $uri/ /index.html;
    }
}

CLI Commands

# Test configuration syntax (always do before reload!)
nginx -t
nginx -T             # test and dump full resolved config

# Control nginx process
nginx -s reload      # graceful reload (no downtime)
nginx -s reopen      # reopen log files (after rotation)
nginx -s quit        # graceful shutdown (wait for connections)
nginx -s stop        # fast shutdown

# Systemd
systemctl start nginx
systemctl enable nginx      # start on boot
systemctl reload nginx      # same as nginx -s reload
systemctl status nginx
journalctl -u nginx -f      # follow logs

# Certbot (Let's Encrypt SSL)
certbot --nginx -d example.com -d www.example.com
certbot renew --dry-run
certbot renew               # usually run via cron/systemd timer

# Key file locations
# /etc/nginx/nginx.conf         main config
# /etc/nginx/sites-available/   available site configs
# /etc/nginx/sites-enabled/     symlinks to active configs
# /etc/nginx/conf.d/            additional configs
# /var/log/nginx/access.log     access logs
# /var/log/nginx/error.log      error logs

# Enable a site (Debian/Ubuntu pattern)
ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/myapp
nginx -t && systemctl reload nginx

Nginx

Nginx for Node.js Apps

Nginx for Node.js Apps Nginx as a reverse proxy in front of Node.js (Next.js, Express, NestJS) handles SSL termination, static asset serving, load balancing, an…

Nginx for Node.js Apps

Nginx as a reverse proxy in front of Node.js (Next.js, Express, NestJS) handles SSL termination, static asset serving, load balancing, and protects the application server from direct internet exposure.

Reverse Proxy Configuration

# /etc/nginx/sites-enabled/nextjs-app.conf

server {
    listen 80;
    server_name myapp.com www.myapp.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name myapp.com www.myapp.com;

    ssl_certificate     /etc/letsencrypt/live/myapp.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/myapp.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    # Security headers
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Content-Type-Options nosniff always;
    add_header X-Frame-Options DENY always;

    # Next.js static assets — serve directly (bypass Node.js entirely)
    location /_next/static/ {
        alias /home/deploy/myapp/.next/static/;
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    # Public folder
    location /public/ {
        alias /home/deploy/myapp/public/;
        expires 30d;
        add_header Cache-Control "public";
    }

    # Proxy everything else to Next.js app (port 3000)
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;

        # Required 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;

        # WebSocket support (Next.js HMR, Socket.io, etc.)
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Timeouts
        proxy_read_timeout    60s;
        proxy_connect_timeout 10s;
        proxy_send_timeout    60s;

        # Buffer settings
        proxy_buffering on;
        proxy_buffer_size 4k;
        proxy_buffers 8 4k;
    }
}

Load Balancing

# upstream block — defines a pool of backend servers
upstream nodejs_cluster {
    # Default: round-robin (requests cycle through servers)
    server 127.0.0.1:3000;
    server 127.0.0.1:3001;
    server 127.0.0.1:3002;

    # keepalive — reuse connections to upstream (big performance win)
    keepalive 32;
}

# Least connections — send to server with fewest active connections
upstream nodejs_leastconn {
    least_conn;
    server 127.0.0.1:3000;
    server 127.0.0.1:3001;
}

# IP hash — sticky sessions (same client -> same server)
upstream nodejs_sticky {
    ip_hash;
    server 127.0.0.1:3000;
    server 127.0.0.1:3001;
}

# Weighted — send 3x more traffic to first server
upstream nodejs_weighted {
    server 127.0.0.1:3000 weight=3;
    server 127.0.0.1:3001 weight=1;
}

# With health checks and fallback
upstream nodejs_resilient {
    server 127.0.0.1:3000;
    server 127.0.0.1:3001;
    server 127.0.0.1:3002 backup;   # only used if others are down

    # Mark server down after 3 failures in 30s, retry after 10s
    # (add to each server line:)
    # max_fails=3 fail_timeout=30s
}

server {
    listen 443 ssl http2;
    server_name myapp.com;
    # ... ssl config ...

    location / {
        proxy_pass http://nodejs_cluster;
        proxy_http_version 1.1;
        proxy_set_header Connection "";  # required for keepalive upstream
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Rate Limiting

# Define rate limit zones in http {} block (outside server {})
# $binary_remote_addr — compact IP representation (4 bytes)
# zone=name:size — shared memory; 1MB ~= 16,000 IPs
http {
    # General API: 10 requests/second per IP
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

    # Auth endpoints: 5 requests/minute per IP (stricter)
    limit_req_zone $binary_remote_addr zone=login:10m rate=5r/m;

    # Return 429 instead of default 503 when rate limited
    limit_req_status 429;
    limit_conn_status 429;
}

server {
    # ...

    # API routes: allow burst of 20 requests, process immediately (nodelay)
    location /api/ {
        limit_req zone=api burst=20 nodelay;
        proxy_pass http://nodejs_cluster;
    }

    # Auth routes: strict, no burst
    location /api/auth/ {
        limit_req zone=login burst=3;
        proxy_pass http://nodejs_cluster;
    }

    # Limit concurrent connections per IP
    limit_conn_zone $binary_remote_addr zone=perip:10m;
    location /download/ {
        limit_conn perip 5;          # max 5 simultaneous downloads per IP
        limit_rate 500k;             # throttle bandwidth to 500KB/s
        proxy_pass http://nodejs_cluster;
    }
}

WebSocket Proxying

# WebSocket connections require the Upgrade and Connection headers
# Nginx needs to pass these through to upgrade HTTP to WS protocol

# map — dynamically set Connection header based on Upgrade presence
http {
    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }
}

server {
    listen 443 ssl http2;
    server_name myapp.com;
    # ... ssl config ...

    # WebSocket endpoint (Socket.io, ws://, Next.js HMR)
    location /socket.io/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host       $host;
        proxy_set_header X-Real-IP  $remote_addr;
        proxy_cache_bypass $http_upgrade;

        # WS connections are long-lived — increase timeouts
        proxy_read_timeout 3600s;  # 1 hour
        proxy_send_timeout 3600s;
    }

    # Regular HTTP routes
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection $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;
    }
}

Nginx notes for developers