Nginx guide

What Nginx does in production

Nginx handles HTTP/HTTPS connections with an event-driven architecture that scales well under concurrency. It serves files from disk, reverse-proxies to app servers (Gunicorn, uWSGI, Node), and can load-balance across upstreams. TLS termination, gzip compression, caching, and rate limiting are configured in plain-text config files — no modules to compile for most use cases.

How a request is handled

When a client connects, the typical workflow is:

1. TCP accept — a worker process accepts the connection on a listen socket
2. TLS handshake — if HTTPS, the certificate is selected by SNI hostname
3. Server block match — Nginx picks a server { } block using listen, server_name, and default-server flags
4. Location match — within the server block, the best-matching location handles the URI (prefix, exact =, regex ~)
5. Handler — static file (root / try_files), proxy (proxy_pass), or redirect (return)
6. Response — logged to access_log; errors go to error_log

If no server_name matches, Nginx uses the default server for that port — usually the first server block defined.

Configuration layout

• Debian/Ubuntu — /etc/nginx/nginx.conf includes sites-enabled/; enable sites with symlinks from sites-available/
• RHEL/CentOS/Rocky — /etc/nginx/nginx.conf includes conf.d/*.conf
• Snippets — shared fragments in /etc/nginx/snippets/ (SSL params, proxy headers)

Test before reload: nginx -t. Apply: systemctl reload nginx.

Key directives to know

• listen — IP and port this server block binds to (default_server marks the fallback)
• server_name — hostnames this server block responds to (exact match -> wildcard -> regex -> default_server
• root / alias — filesystem path for static files; alias replaces the matched location path (e.g. location /images/ { alias /var/www/img; } serves /var/www/img/logo.png for /images/logo.png)
• proxy_pass — upstream URL for reverse proxying; trailing slash behavior matters (e.g proxy_pass http://backend/; strips the location prefix)
• upstream — named backend pool with load-balancing (default: round-robin)
• try_files — try paths in order; common pattern for SPAs (e.g. try_files $uri $uri/ /index.html;)
• client_max_body_size — upload limit (413 if exceeded)
• location — URI matching block (prefix, exact, regex); order matters
• include — pull in other config files
• return / rewrite — URL redirection; return is preferred for simple redirects
• access_log / error_log — logging paths and formats; first place to check on failures
• stream — top-level context for Layer 4 proxying (TCP/UDP)

Location matching priority

Nginx chooses the most specific match: exact = beats prefix (longest wins), then regex in definition order, then general prefix. A common mistake is a broad location / catching requests meant for location /api/ — prefix length and ordering matter.

Layer 4 (TCP/UDP) Proxying

Nginx can proxy any TCP or UDP traffic, not just HTTP. This is handled in the `stream` context (separate from `http`).

Learning resources

• Nginx documentation — nginx.org/en/docs (official reference)
• Server names — nginx.org/en/docs/http/server_names (how server blocks are selected)
• ngx_http_proxy_module — nginx.org/en/docs/http/ngx_http_proxy_module (reverse proxy directives)
• Beginner's guide — nginx.org/en/docs/beginners_guide (configuration walkthrough)