nginx.mdc

---
description: "Nginx: reverse proxy, performance, security headers"
globs: ["*.conf", "nginx.conf"]
alwaysApply: true
---

# Nginx Cursor Rules

You are an expert Nginx administrator. Follow these rules:

## Core Config
- worker_processes auto to match CPU cores
- worker_connections 2048+ for production (default 512 is too low)
- Use epoll (Linux) or kqueue (BSD/Mac) event methods
- keepalive_timeout 65 for client, keepalive 32 for upstream connections
- sendfile on, tcp_nopush on, tcp_nodelay on for static file performance

## Reverse Proxy
- Use upstream blocks for backend pools with load balancing
- proxy_set_header Host $host and X-Real-IP $remote_addr always
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for
- proxy_set_header X-Forwarded-Proto $scheme for HTTPS detection
- proxy_buffering on with reasonable proxy_buffer_size for most APIs
- proxy_connect_timeout, proxy_read_timeout tuned per upstream

## SSL/TLS
- TLS 1.2 and 1.3 only: ssl_protocols TLSv1.2 TLSv1.3
- Strong ciphers: ECDHE+AESGCM:ECDHE+CHACHA20
- ssl_session_cache shared:SSL:50m for session reuse
- OCSP stapling: ssl_stapling on, ssl_stapling_verify on
- Redirect all HTTP to HTTPS with 301

## Security Headers
- X-Content-Type-Options: nosniff
- X-Frame-Options: DENY (or SAMEORIGIN if needed)
- Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
- Content-Security-Policy: default-src self — customize per app
- Hide server version: server_tokens off

## Caching
- Static assets: expires 1y with immutable filenames (hash in filename)
- API responses: proxy_cache with cache key including relevant params
- Use stale-while-revalidate for better UX during cache refresh
- Cache only GET/HEAD — never cache POST or authenticated responses

## Rate Limiting
- limit_req_zone for per-IP rate limiting on login/API endpoints
- burst parameter for absorbing short spikes
- limit_conn_zone for concurrent connection limits
- Return 429 (too many requests) not 503