Nginx Configuration: Complete Guide for Developers 2026

Published February 12, 2026 · 30 min read

Nginx (pronounced "engine-x") powers over a third of all websites on the internet. It serves static files faster than almost anything else, acts as a reverse proxy for application servers, balances load across clusters, terminates SSL/TLS, compresses responses, caches content, and enforces rate limits — all from a single, efficient process. If you deploy anything on a Linux server, you will configure Nginx.

This guide covers every major Nginx configuration topic from architecture fundamentals through production hardening. Each section includes ready-to-use configuration blocks that you can adapt to your own servers.

1. Nginx Architecture and How It Works

Nginx uses a master-worker architecture. When you start Nginx, one master process launches and manages multiple worker processes. The master reads configuration, binds to ports, and handles signals (reload, stop). The workers do all the actual work of accepting connections, reading requests, and sending responses.

Each worker uses an event-driven, non-blocking I/O model. Instead of spawning a thread per connection (like traditional servers), a single worker handles thousands of connections simultaneously using an event loop powered by epoll (Linux), kqueue (BSD/macOS), or similar OS mechanisms. This is why Nginx uses so little memory under heavy load — a worker handling 10,000 connections uses roughly the same memory as one handling 100.

Request processing flows through a series of phases: server selection, URI rewriting, access control, content generation, and logging. Each phase executes the relevant directives from your configuration. Understanding this pipeline explains why directive order sometimes matters and why certain directives only work in certain contexts.

2. Installation and Directory Structure

Installing Nginx

# Ubuntu / Debian
sudo apt update
sudo apt install nginx

# CentOS / RHEL / Fedora
sudo dnf install nginx

# macOS (Homebrew)
brew install nginx

# Verify installation
nginx -v

# Start and enable on boot
sudo systemctl start nginx
sudo systemctl enable nginx

Directory Structure

/etc/nginx/
  nginx.conf              # Main configuration file
  mime.types              # MIME type mappings
  conf.d/                 # Additional config files (included by default)
  sites-available/        # Server block configs (Debian/Ubuntu)
  sites-enabled/          # Symlinks to active configs
  snippets/               # Reusable config fragments

/var/log/nginx/
  access.log              # Request log
  error.log               # Error log

/var/www/                 # Default web root
/usr/share/nginx/html/    # Default welcome page

3. nginx.conf Main Context

The main configuration file defines global settings that affect the entire Nginx instance. Here is a production-ready nginx.conf:

# Main context - global settings
user www-data;
worker_processes auto;          # One worker per CPU core
pid /run/nginx.pid;
error_log /var/log/nginx/error.log warn;

# Maximum open file descriptors per worker
worker_rlimit_nofile 65535;

events {
    worker_connections 4096;    # Max connections per worker
    multi_accept on;            # Accept multiple connections at once
    use epoll;                  # Linux: use epoll for event handling
}

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

    # Performance
    sendfile        on;
    tcp_nopush      on;
    tcp_nodelay     on;
    keepalive_timeout  65;
    types_hash_max_size 2048;

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

    # Include server blocks
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

Key directives: worker_processes auto matches your CPU core count. worker_connections multiplied by worker_processes gives the theoretical maximum simultaneous connections. For a 4-core server with 4096 connections per worker, that is 16,384 concurrent connections.

4. Server Blocks (Virtual Hosts)

Server blocks let you host multiple websites on a single Nginx instance. Each block defines a virtual host with its own domain, root directory, and settings.

# /etc/nginx/sites-available/example.com
server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;
    root /var/www/example.com/public;
    index index.html index.htm;

    # Handle clean URLs
    location / {
        try_files $uri $uri/ $uri.html =404;
    }

    # Custom error pages
    error_page 404 /404.html;
    error_page 500 502 503 504 /50x.html;
}

Enabling a Server Block

# Create the config file
sudo nano /etc/nginx/sites-available/example.com

# Symlink to sites-enabled
sudo ln -s /etc/nginx/sites-available/example.com \
           /etc/nginx/sites-enabled/

# Test configuration and reload
sudo nginx -t
sudo systemctl reload nginx

Default Server and Catch-All

# Catch requests that don't match any server_name
server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name _;
    return 444;    # Close connection with no response
}

5. Location Directives

Location blocks route requests to different handlers based on the URI. Nginx evaluates them in a specific priority order:

server {
    server_name example.com;

    # 1. Exact match (highest priority)
    location = /health {
        return 200 "OK\n";
        add_header Content-Type text/plain;
    }

    # 2. Preferential prefix (^~) - stops regex search
    location ^~ /static/ {
        root /var/www/example.com;
        expires 30d;
    }

    # 3. Regex match (case-sensitive)
    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php-fpm.sock;
        include fastcgi_params;
    }

    # 4. Regex match (case-insensitive)
    location ~* \.(jpg|jpeg|png|gif|ico|svg|webp)$ {
        expires 365d;
        add_header Cache-Control "public, immutable";
    }

    # 5. Prefix match (lowest priority)
    location / {
        try_files $uri $uri/ =404;
    }

    # Nested locations
    location /api/ {
        location /api/v1/ {
            proxy_pass http://backend_v1;
        }
        location /api/v2/ {
            proxy_pass http://backend_v2;
        }
    }
}

Evaluation order: Exact match (=) is checked first. If it matches, Nginx stops immediately. Next, prefix matches are evaluated — if the longest match uses ^~, Nginx stops. Otherwise, regex locations (~ and ~*) are checked top to bottom. If a regex matches, it wins. If no regex matches, the longest prefix match is used.

6. Reverse Proxy Configuration

The reverse proxy is Nginx's most powerful feature. It sits in front of your application servers, handling SSL termination, compression, caching, and load balancing while forwarding requests to backends.

server {
    listen 80;
    server_name app.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;

        # Pass original request information to backend
        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;

        # Connection settings
        proxy_http_version 1.1;
        proxy_set_header Connection "";

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

        # Buffering
        proxy_buffering on;
        proxy_buffer_size 4k;
        proxy_buffers 8 4k;
    }

    # Serve static files directly, bypass proxy
    location /static/ {
        alias /var/www/app/static/;
        expires 30d;
        access_log off;
    }
}

The proxy_set_header directives are critical. Without them, your backend sees 127.0.0.1 as the client IP and loses the original host name. X-Forwarded-For preserves the full proxy chain, while X-Real-IP gives the direct client address.

7. Load Balancing

Nginx distributes traffic across multiple backend servers using the upstream block. Four algorithms cover most use cases:

# Round-robin (default) - requests distributed evenly
upstream backend {
    server 10.0.0.1:3000;
    server 10.0.0.2:3000;
    server 10.0.0.3:3000;
}

# Least connections - sends to server with fewest active connections
upstream backend_lc {
    least_conn;
    server 10.0.0.1:3000;
    server 10.0.0.2:3000;
    server 10.0.0.3:3000;
}

# IP hash - same client always reaches same server (session persistence)
upstream backend_iphash {
    ip_hash;
    server 10.0.0.1:3000;
    server 10.0.0.2:3000;
    server 10.0.0.3:3000;
}

# Weighted - more powerful servers get more traffic
upstream backend_weighted {
    server 10.0.0.1:3000 weight=5;
    server 10.0.0.2:3000 weight=3;
    server 10.0.0.3:3000 weight=1;
}

# Health checks and failover
upstream backend_resilient {
    server 10.0.0.1:3000 max_fails=3 fail_timeout=30s;
    server 10.0.0.2:3000 max_fails=3 fail_timeout=30s;
    server 10.0.0.3:3000 backup;     # Only used when others are down
}

server {
    listen 80;
    server_name app.example.com;

    location / {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_next_upstream error timeout http_502 http_503;
    }
}

max_fails and fail_timeout control passive health checking. After 3 failures within 30 seconds, Nginx marks the server as unavailable and stops sending traffic to it for 30 seconds. proxy_next_upstream tells Nginx to retry the request on the next backend when specific errors occur.

8. SSL/TLS Configuration

Modern SSL/TLS configuration with strong security defaults and Let's Encrypt certificates:

# HTTP to HTTPS redirect
server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}

# HTTPS server
server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name example.com www.example.com;

    # Certificate files (Let's Encrypt)
    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    # Protocols - only TLS 1.2 and 1.3
    ssl_protocols TLSv1.2 TLSv1.3;

    # Ciphers - server preference, strong suites only
    ssl_prefer_server_ciphers on;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;

    # OCSP Stapling - faster TLS handshakes
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem;
    resolver 1.1.1.1 8.8.8.8 valid=300s;

    # Session caching - reduce handshake overhead
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;
    ssl_session_tickets off;

    # HSTS - force HTTPS for 1 year
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    root /var/www/example.com/public;
    index index.html;
}

Let's Encrypt with Certbot

# Install Certbot
sudo apt install certbot python3-certbot-nginx

# Obtain certificate (auto-configures Nginx)
sudo certbot --nginx -d example.com -d www.example.com

# Test automatic renewal
sudo certbot renew --dry-run

# Certbot auto-renewal runs via systemd timer
sudo systemctl status certbot.timer

9. Gzip Compression

Gzip compression reduces response sizes by 60-80%, dramatically improving load times for text-based content.

# In the http block of nginx.conf
gzip on;
gzip_vary on;                    # Add Vary: Accept-Encoding header
gzip_proxied any;                # Compress proxied responses too
gzip_comp_level 5;               # Balance: 1=fastest, 9=smallest
gzip_min_length 256;             # Skip tiny responses
gzip_http_version 1.1;

# Compress these MIME types (text/html is always compressed)
gzip_types
    text/plain
    text/css
    text/javascript
    text/xml
    application/json
    application/javascript
    application/xml
    application/xml+rss
    application/atom+xml
    application/vnd.ms-fontobject
    font/opentype
    font/ttf
    image/svg+xml
    image/x-icon;

gzip_comp_level 5 is the sweet spot. Levels 1-4 compress too little, while levels 6-9 use significantly more CPU with marginal size reductions. Never compress already-compressed formats like JPEG, PNG, WOFF2, or video — it wastes CPU and can increase file size.

10. Caching

Proxy Cache

# Define cache zone in http block
proxy_cache_path /var/cache/nginx/proxy
    levels=1:2
    keys_zone=app_cache:10m       # 10 MB for keys (~80,000 entries)
    max_size=1g                   # 1 GB disk space for cached responses
    inactive=60m                  # Remove items not accessed for 60 min
    use_temp_path=off;

server {
    listen 80;
    server_name app.example.com;

    location / {
        proxy_pass http://backend;
        proxy_cache app_cache;
        proxy_cache_valid 200 10m;
        proxy_cache_valid 404 1m;
        proxy_cache_use_stale error timeout updating http_502 http_503;
        proxy_cache_lock on;             # Prevent cache stampede

        # Pass cache status to client
        add_header X-Cache-Status $upstream_cache_status;
        proxy_cache_bypass $http_cache_control;
    }

    # Skip caching for dynamic content
    location /api/ {
        proxy_pass http://backend;
        proxy_cache off;
    }
}

Static File Browser Caching

# Long-lived cache for fingerprinted assets
location ~* \.(js|css)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
    access_log off;
}

# Moderate cache for images
location ~* \.(jpg|jpeg|png|gif|ico|svg|webp|avif)$ {
    expires 30d;
    add_header Cache-Control "public";
    access_log off;
}

# Short cache for HTML
location ~* \.html$ {
    expires 1h;
    add_header Cache-Control "public, must-revalidate";
}

# No cache for service worker
location = /sw.js {
    expires off;
    add_header Cache-Control "no-store, no-cache, must-revalidate";
}

11. Rate Limiting

Rate limiting protects your server from abuse, brute force attacks, and traffic spikes.

# Define rate limit zones in http block
limit_req_zone $binary_remote_addr zone=general:10m rate=10r/s;
limit_req_zone $binary_remote_addr zone=auth:10m rate=3r/m;
limit_conn_zone $binary_remote_addr zone=addr:10m;

server {
    listen 80;
    server_name app.example.com;

    # General rate limit with burst allowance
    location / {
        limit_req zone=general burst=20 nodelay;
        limit_conn addr 50;
        proxy_pass http://backend;
    }

    # Strict rate limit on authentication
    location /api/login {
        limit_req zone=auth burst=5;
        limit_req_status 429;
        proxy_pass http://backend;
    }

    # No rate limit for static assets
    location /static/ {
        alias /var/www/app/static/;
    }
}

burst=20 nodelay allows up to 20 requests to be processed immediately above the base rate, then rejects excess requests. Without nodelay, burst requests are queued and delayed. $binary_remote_addr uses 4 bytes per IPv4 address instead of the string form, so 10 MB holds about 160,000 addresses.

12. Security Headers and Hardening

server {
    # Security headers
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "0" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
    add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
    add_header Content-Security-Policy
        "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self';"
        always;

    # HSTS (only enable when you are committed to HTTPS)
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;

    # Hide Nginx version
    server_tokens off;

    # Block access to hidden files (.git, .env, .htaccess)
    location ~ /\. {
        deny all;
        access_log off;
        log_not_found off;
    }

    # Block common vulnerability scanners
    location ~* (wp-admin|wp-login|xmlrpc\.php|\.asp|\.aspx) {
        return 444;
    }

    # Restrict request methods
    if ($request_method !~ ^(GET|HEAD|POST|PUT|PATCH|DELETE)$) {
        return 405;
    }

    # Limit request body size
    client_max_body_size 10m;
}

The always parameter ensures headers are added to all responses, including error pages. Without it, Nginx only adds headers to 2xx and 3xx responses. server_tokens off removes the version number from error pages and the Server header, reducing information exposure.

13. Logging and Monitoring

# Custom log format with timing information
log_format detailed '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent" '
                    'rt=$request_time uct=$upstream_connect_time '
                    'uht=$upstream_header_time urt=$upstream_response_time';

# JSON log format (for log aggregation tools)
log_format json escape=json
    '{'
        '"time":"$time_iso8601",'
        '"remote_addr":"$remote_addr",'
        '"request":"$request",'
        '"status":$status,'
        '"body_bytes_sent":$body_bytes_sent,'
        '"request_time":$request_time,'
        '"http_referer":"$http_referer",'
        '"http_user_agent":"$http_user_agent"'
    '}';

server {
    # Per-server access log with detailed format
    access_log /var/log/nginx/app.access.log detailed;

    # Conditional logging - skip health check noise
    map $request_uri $loggable {
        /health   0;
        /ping     0;
        default   1;
    }
    access_log /var/log/nginx/app.access.log detailed if=$loggable;

    # Disable logging for static assets
    location /static/ {
        access_log off;
    }
}

Log Rotation

# /etc/logrotate.d/nginx
/var/log/nginx/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 www-data adm
    sharedscripts
    postrotate
        [ -f /var/run/nginx.pid ] && kill -USR1 $(cat /var/run/nginx.pid)
    endscript
}

14. Common Patterns

Single-Page Application (SPA)

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

    # All routes fall back to index.html for client-side routing
    location / {
        try_files $uri $uri/ /index.html;
    }

    # Cache static assets aggressively
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # Never cache the HTML shell
    location = /index.html {
        expires -1;
        add_header Cache-Control "no-store, must-revalidate";
    }
}

API Gateway

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

    # Route to microservices by path
    location /auth/ {
        proxy_pass http://auth-service:4000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /users/ {
        proxy_pass http://user-service:4001/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /products/ {
        proxy_pass http://product-service:4002/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # CORS headers
    add_header Access-Control-Allow-Origin "https://app.example.com" always;
    add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
    add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;

    if ($request_method = OPTIONS) {
        return 204;
    }
}

WebSocket Proxy

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    server_name ws.example.com;

    location /ws/ {
        proxy_pass http://127.0.0.1:8080;
        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_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

15. Performance Tuning and Best Practices

worker_processes auto;
worker_rlimit_nofile 65535;

events {
    worker_connections 4096;
    multi_accept on;
    use epoll;
}

http {
    # File I/O optimization
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;

    # Keepalive tuning
    keepalive_timeout 65;
    keepalive_requests 1000;

    # Upstream keepalive (critical for proxy performance)
    upstream backend {
        server 127.0.0.1:3000;
        keepalive 32;                # Connection pool size
    }

    server {
        location / {
            proxy_pass http://backend;
            proxy_http_version 1.1;
            proxy_set_header Connection "";  # Required for upstream keepalive
        }
    }

    # Buffer tuning
    client_body_buffer_size 16k;
    client_header_buffer_size 1k;
    large_client_header_buffers 4 16k;

    # Timeouts
    client_body_timeout 12;
    client_header_timeout 12;
    send_timeout 10;

    # Open file cache - avoid repeated filesystem lookups
    open_file_cache max=10000 inactive=20s;
    open_file_cache_valid 30s;
    open_file_cache_min_uses 2;
    open_file_cache_errors on;
}

Key performance principles: sendfile bypasses user space for file transfers. tcp_nopush coalesces small writes into full TCP segments. keepalive on upstreams avoids the overhead of establishing a new TCP connection per proxied request — this alone can improve throughput by 20-40%. The open file cache avoids repeated filesystem lookups for frequently accessed files.

16. Troubleshooting Common Errors

502 Bad Gateway

# Backend is not running or unreachable
sudo ss -tlnp | grep 3000       # Is the backend listening?
sudo tail -f /var/log/nginx/error.log  # What does Nginx say?

# Common causes:
# - Backend crashed or hasn't started
# - Wrong port in proxy_pass
# - Unix socket permission mismatch
# - SELinux blocking connection (CentOS/RHEL):
sudo setsebool -P httpd_can_network_connect 1

413 Request Entity Too Large

# Increase the upload limit in server or location block
client_max_body_size 50m;

403 Forbidden

# Check file ownership and permissions
ls -la /var/www/example.com/
sudo chown -R www-data:www-data /var/www/example.com/
sudo chmod -R 755 /var/www/example.com/

# Check the error log for the exact path
sudo tail /var/log/nginx/error.log

Configuration Testing

# Always test before reloading
sudo nginx -t

# Dump the full resolved configuration
sudo nginx -T

# Graceful reload (zero downtime)
sudo systemctl reload nginx

# Check what process holds the ports
sudo ss -tlnp | grep ':80\|:443'

Frequently Asked Questions

Conclusion

Nginx is the backbone of modern web infrastructure. Whether you are serving a static site, proxying to a Node.js application, balancing load across a cluster, or building a microservices API gateway, the same core concepts apply: server blocks route domains, location blocks match URIs, and directives control behavior.

Start with a simple static server or reverse proxy, get comfortable with nginx -t and systemctl reload nginx, then incrementally add SSL/TLS, gzip, caching, and rate limiting. Always test configuration before reloading, keep the error log open during changes, and use nginx -T to dump the full resolved configuration when debugging.

Learn More

• Docker Compose: The Complete Guide — define multi-container applications with Nginx as a reverse proxy
• GitHub Actions CI/CD Guide — automate Nginx configuration deployment
• HTTP Request Tester — test your Nginx server responses and headers
• Linux Commands Guide — essential server management commands