Nginx

---
name: Nginx
slug: nginx
version: 1.0.1
description: Configure Nginx for reverse proxy, load balancing, SSL termination, and high-performance static serving.
---

## When to Use

User needs Nginx expertise — from basic server blocks to production configurations. Agent handles reverse proxy, SSL, caching, and performance tuning.

## Quick Reference

| Topic | File |
|-------|------|
| Reverse proxy patterns | `proxy.md` |
| SSL/TLS configuration | `ssl.md` |
| Performance tuning | `performance.md` |
| Common configurations | `examples.md` |

## Location Matching

- Exact `=` first, then `^~` prefix, then regex `~`/`~*`, then longest prefix
- `location /api` matches `/api`, `/api/`, `/api/anything` — prefix match
- `location = /api` only matches exactly `/api` — not `/api/`
- `location ~ \.php$` is regex, case-sensitive — `~*` for case-insensitive
- `^~` stops regex search if prefix matches — use for static files

## proxy_pass Trailing Slash

- `proxy_pass http://backend` preserves location path — `/api/users` → `/api/users`
- `proxy_pass http://backend/` replaces location path — `/api/users` → `/users`
- Common mistake: missing slash = double path — or unexpected routing
- Test with `curl -v` to see actual backend request

## try_files

- `try_files $uri $uri/ /index.html` for SPA — checks file, then dir, then fallback
- Last argument is internal redirect — or `=404` for error
- `$uri/` tries directory with index — set `index index.html`
- Don't use for proxied locations — use `proxy_pass` directly

## Proxy Headers

- `proxy_set_header Host $host` — backend sees original host, not proxy IP
- `proxy_set_header X-Real-IP $remote_addr` — client IP, not proxy
- `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for` — append to chain
- `proxy_set_header X-Forwarded-Proto $scheme` — for HTTPS detection

## Upstream

- Define servers in `upstream` block — `upstream backend { server 127.0.0.1:3000; }`
- `proxy_pass http://backend` uses upstream — load balancing included
- Health checks with `max_fails` and `fail_timeout` — marks server unavailable
- `keepalive 32` for connection pooling — reduces connection overhead

## SSL/TLS

- `ssl_certificate` is full chain — cert + intermediates, not just cert
- `ssl_certificate_key` is private key — keep permissions restricted
- `ssl_protocols TLSv1.2 TLSv1.3` — disable older protocols
- `ssl_prefer_server_ciphers on` — server chooses cipher, not client

## Common Mistakes

- `nginx -t` before `nginx -s reload` — test config first
- Missing semicolon — syntax error, vague message
- `root` inside `location` — prefer in `server`, override only when needed
- `alias` vs `root` — alias replaces location, root appends location
- Variables in `if` — many things break inside if, avoid complex logic

## Variables

- `$uri` is decoded, normalized path — `/foo%20bar` becomes `/foo bar`
- `$request_uri` is original with query string — unchanged from client
- `$args` is query string — `$arg_name` for specific parameter
- `$host` from Host header — `$server_name` from config

## Performance

- `worker_processes auto` — matches CPU cores
- `worker_connections 1024` — per worker, multiply by workers for max
- `sendfile on` — kernel-level file transfer
- `gzip on` only for text — `gzip_types text/plain application/json ...`
- `gzip_min_length 1000` — small files not worth compressing

## Logging

- `access_log off` for static assets — reduces I/O
- Custom log format with `log_format` — add response time, upstream time
- `error_log` level: `debug`, `info`, `warn`, `error` — debug is verbose
- Conditional logging with `map` and `if` — skip health checks