Contexts

NGINX configuration is hierarchical. Each directive is valid only inside specific contexts.

Hierarchy (simplified):

main
 └── http
      └── server
           └── location

Each lower context inherits settings from the higher context unless overridden.

Main Context (Global Context)

• What it is:
  • The top-level context
  • Defined outside of any blocks
  • Affects the entire NGINX instance
• What it controls:
  • Worker processes
  • User/group
  • Error logging
  • Performance tuning
  • Global limits

Common Directives

Directive	Purpose
user	OS user for worker processes
worker_processes	Number of worker processes
pid	PID file location
error_log	Global error log
worker_rlimit_nofile	File descriptor limit

Example

user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log warn;
pid /run/nginx.pid;

Explanation

• worker_processes auto; → One worker per CPU core
• user nginx; → Workers run as nginx user
• error_log → Global logging applies everywhere unless overridden

HTTP Context

• What it is
  • Defined using the http block
  • Required for web traffic (HTTP/HTTPS)
  • Contains server blocks
• What it controls
  • Web-related configuration
  • MIME types
  • Logging format
  • Compression
  • Default behavior for all servers

Common directives

Directive	Purpose
include mime.types	File type mapping
log_format	Define access log format
access_log	Enable access logging
sendfile	Efficient file transfer
keepalive_timeout	Connection reuse
gzip	Compression

Example

Directive	Purpose
include mime.types	File type mapping
log_format	Define access log format
access_log	Enable access logging
sendfile	Efficient file transfer
keepalive_timeout	Connection reuse
gzip	Compression

Explanation

• include mime.types; → Maps .html, .jpg, etc.
• log_format → Defines reusable logging format
• sendfile on; → Faster static file serving

Server Context

• What it is
  • Defined using server inside http
  • Represents a virtual host
  • Handles requests for specific IPs/domains/ports
• What it controls
  • Domain names
  • Ports
  • SSL configuration
  • Root directories
  • Default request handling

Common directives

Directive	Purpose
listen	Port/IP to listen on
server_name	Domain names
root	Document root
index	Default file
error_page	Custom error pages

Example

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

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

• listen 80; → Accept HTTP traffic
• server_name → Domain matching
• root → Base directory for files

Location Context

• What it is
  • Defined using location inside a server
  • Matches URIs (paths) of requests
• What it controls
  • Routing logic
  • Static vs dynamic content
  • Proxying
  • Access control
  • Rewriting URLs

Location matching types

Type	Meaning
location /	Prefix match
location = /	Exact match
location ~	Regex (case-sensitive)
location ~*	Regex (case-insensitive)
location ^~	Priority prefix

Example

location /images/ {
    root /var/www/assets;
}

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

• /images/ → Matches /images/logo.png
• ~ \.php$ → Regex match for PHP files
• fastcgi_pass → Sends PHP to PHP-FPM

Complete Example

user nginx;
worker_processes auto;

events {
    worker_connections 1024;
}

http {
    include mime.types;
    default_type text/plain;

    server {
        listen 80;
        server_name example.com;

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

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

        location /api/ {
            proxy_pass http://backend_server;
        }

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

Request Flow (How NGINX Uses Contexts)

1. Main → Sets global worker behavior
2. HTTP → Enables web functionality
3. Server → Chooses correct virtual host
4. Location → Routes request to correct handler

Example request:

GET http://example.com/api/users

• Matched server_name example.com
• Matched location /api/
• Forwarded to backend via proxy_pass