Comprehensive Guide to Nginx

Introduction

Nginx (pronounced "engine-x") is a powerful, high-performance web server, reverse proxy, load balancer, and HTTP cache. Originally created to solve the C10K problem (handling 10,000+ concurrent connections), Nginx has grown to become one of the most popular web servers in the world, powering approximately 30% of all websites.

This guide will walk you through everything you need to know to get started with Nginx, from installation to advanced configuration techniques.

Why Choose Nginx?

Before diving into the technical details, let's understand why Nginx might be the right choice for your infrastructure:

High Performance: Asynchronous, event-driven architecture that can handle thousands of concurrent connections with minimal resource usage
Stability: Known for its rock-solid reliability even under heavy loads
Flexibility: Works as a web server, reverse proxy, load balancer, and more
Simple Configuration: Clean, declarative configuration syntax
Active Development: Regular updates and improvements
Wide Adoption: Extensive community support and documentation

Installation

On Ubuntu/Debian

# Update package lists
sudo apt update

# Install Nginx
sudo apt install nginx

# Start Nginx
sudo systemctl start nginx

# Enable Nginx to start on boot
sudo systemctl enable nginx

# Check status
sudo systemctl status nginx

On CentOS/RHEL

# Install EPEL repository first (if not already installed)
sudo yum install epel-release

# Install Nginx
sudo yum install nginx

# Start Nginx
sudo systemctl start nginx

# Enable Nginx to start on boot
sudo systemctl enable nginx

# Check status
sudo systemctl status nginx

On macOS (using Homebrew)

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Nginx
brew install nginx

# Start Nginx
brew services start nginx

On Windows

For Windows, you can download the Windows binary from the official Nginx website and follow these steps:

Extract the zip file to a location like C:\nginx
Open Command Prompt as Administrator
Navigate to the Nginx directory: cd C:\nginx
Start Nginx: start nginx

Basic Concepts

Before we dive into configuration, let's understand some key Nginx concepts:

1. Master and Worker Processes

Nginx operates with a master process and multiple worker processes:

Master Process: Reads configuration, manages worker processes
Worker Processes: Handle actual processing of connections

2. Directives and Contexts

The Nginx configuration consists of:

Directives: Individual configuration instructions (e.g., server_name example.com;)
Contexts: Sections that group related directives (e.g., http, server, location)

3. Virtual Hosts (Server Blocks)

Similar to Apache's virtual hosts, Nginx uses server blocks to define settings for specific domains or IP addresses.

Basic Configuration

The main Nginx configuration file is typically located at:

/etc/nginx/nginx.conf (Linux)
/usr/local/etc/nginx/nginx.conf (macOS with Homebrew)
C:\nginx\conf\nginx.conf (Windows)

Understanding the Default Configuration

A basic nginx.conf file looks like this:

user www-data;
worker_processes auto;
pid /run/nginx.pid;
include /etc/nginx/modules-enabled/*.conf;

events {
    worker_connections 768;
    # multi_accept on;
}

http {
    # Basic Settings
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    types_hash_max_size 2048;

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

    # Logging Settings
    access_log /var/log/nginx/access.log;
    error_log /var/log/nginx/error.log;

    # Gzip Settings
    gzip on;

    # Virtual Host Configs
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

Let's break down the key components:

user: Defines which user the worker processes will run as
worker_processes: Number of worker processes to spawn (auto = one per CPU core)
events: Configuration for the event-based processing model
worker_connections: Maximum connections each worker can handle
http: Main context for HTTP-related directives
include: Imports additional configuration files

Creating Your First Server Block

Let's create a basic server block to serve a static website:

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

    root /var/www/example.com;
    index index.html index.htm;

    location / {
        try_files $uri $uri/ =404;
    }
}

Save this to /etc/nginx/sites-available/example.com and create a symbolic link to enable it:

sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/
sudo nginx -t  # Test the configuration
sudo systemctl reload nginx  # Apply changes

Setting Up Nginx as a Reverse Proxy

One of Nginx's most common use cases is as a reverse proxy for application servers like Node.js, Ruby on Rails, or Django.

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

    location / {
        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;
        proxy_cache_bypass $http_upgrade;
    }
}

This configuration proxies all requests to a local application running on port 3000.

Load Balancing with Nginx

Nginx can distribute traffic across multiple backend servers:

upstream backend_servers {
    server backend1.example.com weight=3;
    server backend2.example.com;
    server backup1.example.com backup;
}

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

    location / {
        proxy_pass http://backend_servers;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

In this example:

weight=3 means backend1 gets 3x more requests than backend2
backup means this server is only used when others are unavailable

SSL/TLS Configuration

Securing your website with HTTPS is essential. Here's how to configure Nginx with SSL:

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

server {
    listen 443 ssl;
    server_name secure.example.com;

    ssl_certificate /etc/nginx/ssl/example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/example.com.key;

    # Modern SSL configuration (recommended)
    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:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;

    # HSTS (optional but recommended)
    add_header Strict-Transport-Security "max-age=63072000" always;

    root /var/www/secure.example.com;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

Setting Up with Let's Encrypt

For free SSL certificates, Let's Encrypt is a popular choice:

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

# Obtain and install certificate
sudo certbot --nginx -d example.com -d www.example.com

# Verify auto-renewal
sudo systemctl status certbot.timer

Optimizing Nginx Performance

Cache Configuration

http {
    # File cache settings
    open_file_cache max=1000 inactive=20s;
    open_file_cache_valid 30s;
    open_file_cache_min_uses 2;
    open_file_cache_errors on;

    # Gzip compression
    gzip on;
    gzip_comp_level 5;
    gzip_min_length 256;
    gzip_proxied any;
    gzip_vary on;
    gzip_types
        application/atom+xml
        application/javascript
        application/json
        application/ld+json
        application/manifest+json
        application/rss+xml
        application/vnd.geo+json
        application/vnd.ms-fontobject
        application/x-font-ttf
        application/x-web-app-manifest+json
        application/xhtml+xml
        application/xml
        font/opentype
        image/bmp
        image/svg+xml
        image/x-icon
        text/cache-manifest
        text/css
        text/plain
        text/vcard
        text/vnd.rim.location.xloc
        text/vtt
        text/x-component
        text/x-cross-domain-policy;
}

Worker Optimization

# Set to number of CPU cores
worker_processes auto;

# Adjust worker connections based on system limits
worker_rlimit_nofile 65535;
events {
    worker_connections 65535;
    multi_accept on;
    use epoll;
}

Buffer Optimization

http {
    client_body_buffer_size 16k;
    client_header_buffer_size 1k;
    client_max_body_size 10m;
    large_client_header_buffers 4 8k;
}

Security Enhancements

Basic Security Headers

server {
    # Other configuration...

    # Security headers
    add_header X-Content-Type-Options nosniff;
    add_header X-Frame-Options SAMEORIGIN;
    add_header X-XSS-Protection "1; mode=block";
    add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' https://www.google-analytics.com; img-src 'self' data: https://www.google-analytics.com; style-src 'self' 'unsafe-inline'; font-src 'self'; object-src 'none'";
    add_header Referrer-Policy strict-origin-when-cross-origin;

    # Hide Nginx version
    server_tokens off;
}

Rate Limiting

http {
    # Define a zone for rate limiting
    limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;

    server {
        # Apply rate limiting to login endpoint
        location /login {
            limit_req zone=one burst=5 nodelay;
            # Rest of your configuration...
        }
    }
}

Logging and Monitoring

Custom Log Formats

http {
    log_format detailed '$remote_addr - $remote_user [$time_local] '
                        '"$request" $status $body_bytes_sent '
                        '"$http_referer" "$http_user_agent" '
                        '$request_time $upstream_response_time $pipe';

    access_log /var/log/nginx/access.log detailed;
    error_log /var/log/nginx/error.log warn;
}

Log Rotation

Nginx log files can grow quickly. Most Linux distributions configure log rotation automatically, but you can check the config at /etc/logrotate.d/nginx.

Advanced Features

HTTP/2 Support

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

    # SSL configuration...
}

WebSocket Support

server {
    # Other configuration...

    location /websocket/ {
        proxy_pass http://websocket_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Dynamic Modules

Nginx supports extending functionality through modules. For example, to add GeoIP functionality:

sudo apt install nginx-module-geoip

Then in your configuration:

load_module modules/ngx_http_geoip_module.so;

http {
    geoip_country /usr/share/GeoIP/GeoIP.dat;

    # Use GeoIP data in configuration
    server {
        location / {
            if ($geoip_country_code = "US") {
                return 302 https://us.example.com$request_uri;
            }
        }
    }
}

Troubleshooting Common Issues

Testing Configuration

Always test configuration changes before applying them:

sudo nginx -t

Checking Logs

Logs are your best friend when troubleshooting:

sudo tail -f /var/log/nginx/error.log

Debugging Configuration

For deeper debugging, increase the logging level:

error_log /var/log/nginx/error.log debug;

Common Issues and Solutions

Permission Problems

sudo chown -R www-data:www-data /var/www/example.com
sudo chmod -R 755 /var/www/example.com

Port Binding Issues

# Check if something else is using port 80
sudo netstat -tulpn | grep :80

SSL Certificate Problems

# Verify certificate and key
sudo openssl x509 -in /etc/nginx/ssl/example.com.crt -text -noout
sudo openssl rsa -in /etc/nginx/ssl/example.com.key -check

Best Practices

Keep configurations in separate files rather than one monolithic file
Use includes to maintain organization
Version control your configurations to track changes
Start with minimal configurations and add only what you need
Use meaningful names for server blocks and upstream groups
Comment your configuration for future reference
Regularly update Nginx to benefit from security patches and new features
Monitor performance and adjust configurations as needed
Back up configurations before major changes
Use staging environments to test configurations before deploying to production

Conclusion

Nginx is a powerful and flexible web server and reverse proxy with capabilities that extend far beyond simply serving static files. Its efficiency, scalability, and ease of configuration make it an excellent choice for everything from small personal websites to large-scale enterprise applications.

By understanding the concepts covered in this guide, you now have the foundation to leverage Nginx effectively in your web infrastructure. As with any technology, practice and experimentation are key to mastery, so don't hesitate to set up test environments and explore the many features Nginx has to offer.