Understanding Nginx Configuration: A Comprehensive Guide

1. Directives: The Building Blocks

Nginx consists of modules controlled by directives specified in configuration files. A directive is an option with a specific value, always ending with a semicolon.

Example Directives

listen 80;
server_name example.com www.example.com;
root /var/www/html;
index index.html index.php;

In the example above:

• listen is the directive, 80 is the value
• server_name is the directive, example.com www.example.com are the values
• Each directive ends with a semicolon (;)
• Lines starting with # are comments

2. Contexts: Organizing Directives

A context is a special type of directive that encloses other directives within curly brackets { }. It's also called a context block.

Context Example

events {
    worker_connections 1024;
    multi_accept on;
}

http {
    include mime.types;
    default_type application/octet-stream;
    
    server {
        listen 80;
        server_name example.com;
        
        location / {
            root /var/www/html;
            index index.html;
        }
    }
}

3. Main Nginx Contexts

4. Configuration Workflow

Testing and Reloading Commands

Example Error Resolution

# Incorrect directive (will cause error)
routes /var/www/html;

# Correct directive
root /var/www/html;

5. Location Context and Modifiers

The location context defines how Nginx responds to requests for resources. Modifiers determine the matching behavior.

Understanding Request URIs

https://example.com/images/photo.jpg
         ↓         ↓           ↓
     protocol   domain    request URI

Location Modifiers

Modifier Examples

location = /xmlrpc.php {
    return 403;
}

location ^~ /images {
    return 301 /new-images;
}

location ~ \.ico$ {
    return 403;
}

location ~* \.php$ {
    fastcgi_pass unix:/var/run/php/php-fpm.sock;
}

location /blog {
    root /var/www/html;
}

Matching Priority Flow

6. The try_files Directive

The try_files directive checks for the existence of files in the specified order and uses the first found file for request processing.

Basic Syntax

try_files file1 file2 ... fallback;

Example 1: Basic File Serving

location / {
    root /var/www/example.com/public_html;
    try_files $uri $uri/ /other/index.html;
}

Example 2: WordPress Configuration

location / {
    try_files $uri $uri/ /index.php$is_args$args;
}

Breakdown:

• $uri - Check if the requested file exists
• $uri/ - Check if the requested directory exists
• /index.php$is_args$args - Pass request to index.php with query parameters

Example 3: Caching with W3 Total Cache

location / {
    try_files /wp-content/cache/page_enhanced/$uri/_index.html 
              $uri 
              $uri/ 
              /index.php$is_args$args;
}

Example 4: PHP Security Hardening

location ~ \.php$ {
    try_files $uri =404;
    fastcgi_pass unix:/var/run/php/php-fpm.sock;
    fastcgi_index index.php;
    include fastcgi_params;
}

This configuration checks if the PHP file exists before processing it. If the file doesn't exist, it returns a 404 error instead of passing a non-existent file to PHP-FPM.

7. Complete Configuration Example

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

    # Exact match - deny xmlrpc.php
    location = /xmlrpc.php {
        return 403;
    }

    # Deny access to any .php files in uploads
    location ~* ^/uploads/.*\.php$ {
        return 403;
    }

    # Main location with try_files
    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }

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

    # Deny access to hidden files
    location ~ /\. {
        deny all;
    }

    # Cache static files
    location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}

8. Best Practices Summary

9. Common Troubleshooting