Nginx powers a significant portion of the internet, yet its configuration syntax trips up even experienced engineers. Here’s a practical guide to the patterns you’ll actually use.

Basic Structure

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# /etc/nginx/nginx.conf
user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;
    
    # Include site configs
    include /etc/nginx/conf.d/*.conf;
}

Site configs go in /etc/nginx/conf.d/ or /etc/nginx/sites-enabled/.

Simple Reverse Proxy

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

server {
    listen 80;
    server_name app.example.com;
    
    location / {
        proxy_pass http://localhost:3000;
        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;
    }
}

The headers tell your app about the original request (important for logging, redirects, etc.).

SSL/TLS Configuration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

server {
    listen 443 ssl http2;
    server_name app.example.com;
    
    ssl_certificate /etc/letsencrypt/live/app.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;
    
    # Modern SSL config
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;
    
    # HSTS
    add_header Strict-Transport-Security "max-age=31536000" always;
    
    location / {
        proxy_pass http://localhost:3000;
        # ... proxy headers
    }
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    server_name app.example.com;
    return 301 https://$server_name$request_uri;
}

Location Matching

Order matters. Nginx uses the most specific match:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# Exact match (highest priority)
location = /health {
    return 200 "OK";
}

# Prefix match (preferential)
location ^~ /static/ {
    root /var/www;
}

# Regex match (case sensitive)
location ~ \.php$ {
    # PHP handling
}

# Regex match (case insensitive)
location ~* \.(jpg|jpeg|png|gif)$ {
    expires 30d;
}

# Prefix match (lowest priority)
location / {
    proxy_pass http://backend;
}

Priority: = > ^~ > ~/~* > prefix

Static Files

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

server {
    listen 80;
    server_name static.example.com;
    root /var/www/static;
    
    # Enable gzip
    gzip on;
    gzip_types text/plain text/css application/json application/javascript;
    
    # Cache static assets
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
    
    # SPA fallback
    location / {
        try_files $uri $uri/ /index.html;
    }
}

Load Balancing

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

upstream backend {
    least_conn;  # Or: round_robin, ip_hash
    
    server 10.0.0.1:3000 weight=3;
    server 10.0.0.2:3000;
    server 10.0.0.3:3000 backup;
}

server {
    listen 80;
    server_name app.example.com;
    
    location / {
        proxy_pass http://backend;
        proxy_next_upstream error timeout http_500;
    }
}

Strategies:

  • round_robin (default): Rotate through servers
  • least_conn: Send to server with fewest connections
  • ip_hash: Stick sessions to same server

WebSocket Proxy

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

location /ws {
    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    
    # Timeout for WebSocket connections
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

Rate Limiting

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

http {
    # Define rate limit zone
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
    
    server {
        location /api/ {
            limit_req zone=api burst=20 nodelay;
            proxy_pass http://backend;
        }
    }
}
  • rate=10r/s: 10 requests per second
  • burst=20: Allow 20 requests in queue
  • nodelay: Process burst immediately (don’t delay)

Basic Auth

1
2
3
4
5
6

location /admin {
    auth_basic "Admin Area";
    auth_basic_user_file /etc/nginx/.htpasswd;
    
    proxy_pass http://localhost:3000;
}

Create password file:

1

htpasswd -c /etc/nginx/.htpasswd admin

Custom Error Pages

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

server {
    error_page 404 /404.html;
    error_page 500 502 503 504 /50x.html;
    
    location = /404.html {
        root /var/www/errors;
        internal;
    }
    
    location = /50x.html {
        root /var/www/errors;
        internal;
    }
}

Logging

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

http {
    log_format main '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent" '
                    '$request_time';
    
    access_log /var/log/nginx/access.log main;
    
    server {
        # Per-site logging
        access_log /var/log/nginx/app.access.log main;
        error_log /var/log/nginx/app.error.log;
    }
}

JSON logging for parsing:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

log_format json escape=json '{'
    '"time":"$time_iso8601",'
    '"remote_addr":"$remote_addr",'
    '"method":"$request_method",'
    '"uri":"$request_uri",'
    '"status":$status,'
    '"body_bytes":$body_bytes_sent,'
    '"request_time":$request_time,'
    '"user_agent":"$http_user_agent"'
'}';

Security Headers

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

server {
    # Prevent clickjacking
    add_header X-Frame-Options "SAMEORIGIN" always;
    
    # XSS protection
    add_header X-Content-Type-Options "nosniff" always;
    
    # Referrer policy
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
    
    # CSP (customize for your app)
    add_header Content-Security-Policy "default-src 'self'" always;
}

Testing Configuration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# Test syntax
nginx -t

# Test with specific config
nginx -t -c /etc/nginx/nginx.conf

# Reload without downtime
nginx -s reload
# or
systemctl reload nginx

# Check running config
nginx -T

Common Mistakes

Missing semicolons:

1
2
3
4
5

# Wrong
proxy_pass http://backend

# Right
proxy_pass http://backend;

Trailing slash mismatch:

1
2
3
4
5
6
7
8

# If backend expects /api/users but you send /api/users/
location /api {
    proxy_pass http://backend;  # Sends /api/users
}

location /api/ {
    proxy_pass http://backend/;  # Sends /users (strips /api/)
}

Not reloading after changes:

1

systemctl reload nginx  # Don't forget!

Production Checklist

  • SSL configured with modern ciphers
  • HTTP redirects to HTTPS
  • Security headers added
  • Gzip enabled for text content
  • Static assets have cache headers
  • Rate limiting on sensitive endpoints
  • Access and error logs configured
  • nginx -t passes before reload

Nginx is the Swiss Army knife of web infrastructure. Master these patterns and you can handle most production scenarios.

Where to Host

Need a server for nginx? Get started with free credits:

  • DigitalOcean — $200 free credit. Spin up an Ubuntu droplet in 60 seconds.
  • Vultr — $100 free credit. Global server locations.
  • Hetzner — Budget-friendly European hosting.

Disclosure: Some links are affiliate links.