cfsa-antigravity 1.0.0

package/template/.agent/skill-library/stack/devops/nginx/SKILL.md

@@ -0,0 +1,841 @@
+---
+name: nginx
+description: "Comprehensive Nginx configuration guide covering server blocks, location matching, reverse proxy, SSL/TLS, load balancing, caching, compression, rate limiting, security headers, access control, logging, HTTP/2 and HTTP/3, rewrites, try_files, API gateway patterns, and performance tuning. Use when configuring Nginx as a web server, reverse proxy, load balancer, or API gateway."
+version: 1.0.0
+---
+
+# Nginx
+
+## 1. Philosophy
+
+Nginx is an **event-driven, non-blocking web server** that excels at serving static content, reverse proxying, load balancing, and acting as an API gateway. Its configuration is declarative -- you describe the desired behavior, and Nginx handles the event loop.
+
+**Key principles**:
+- Configuration is hierarchical. Directives inherit from outer blocks to inner blocks.
+- Location matching has specific precedence rules. Know them or debug endlessly.
+- Upstream blocks handle backend pools. Never hardcode backend addresses in location blocks.
+- Security headers are not optional. Every response must include them.
+- Test before reload. Always run `nginx -t` before applying configuration changes.
+
+---
+
+## 2. Server Blocks (Virtual Hosts)
+
+### Basic Server Block
+
+```nginx
+server {
+    listen 80;
+    listen [::]:80;
+    server_name example.com www.example.com;
+
+    # Redirect HTTP to HTTPS
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    listen [::]:443 ssl http2;
+    server_name example.com www.example.com;
+
+    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
+
+    root /var/www/example.com/public;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ =404;
+    }
+}
+```
+
+### Multiple Domains
+
+```nginx
+# Catch-all for undefined domains
+server {
+    listen 80 default_server;
+    server_name _;
+    return 444;  # Close connection without response
+}
+
+# Application domain
+server {
+    listen 80;
+    server_name app.example.com;
+    # ...
+}
+
+# API domain
+server {
+    listen 80;
+    server_name api.example.com;
+    # ...
+}
+```
+
+---
+
+## 3. Location Matching
+
+Nginx processes location blocks in a specific precedence order. Understanding this order prevents subtle routing bugs.
+
+### Matching Precedence (Highest to Lowest)
+
+```nginx
+# 1. Exact match (highest priority)
+location = /health {
+    return 200 "OK";
+    add_header Content-Type text/plain;
+}
+
+# 2. Preferential prefix match (stops searching)
+location ^~ /static/ {
+    root /var/www;
+    expires 30d;
+}
+
+# 3. Regular expression match (first match wins, case-sensitive)
+location ~ \.php$ {
+    fastcgi_pass unix:/run/php/php-fpm.sock;
+}
+
+# 4. Regular expression match (case-insensitive)
+location ~* \.(jpg|jpeg|png|gif|ico|svg|webp)$ {
+    expires 365d;
+    add_header Cache-Control "public, immutable";
+}
+
+# 5. Prefix match (longest match wins)
+location /api/ {
+    proxy_pass http://backend;
+}
+
+# 6. Default prefix match
+location / {
+    try_files $uri $uri/ /index.html;
+}
+```
+
+### Common Mistake
+
+```nginx
+# BAD: regex location takes precedence over prefix
+location /api/ {
+    proxy_pass http://backend;
+}
+
+location ~ ^/api/internal {
+    return 403;  # This OVERRIDES the /api/ prefix above
+}
+
+# GOOD: Use ^~ to prevent regex override
+location ^~ /api/internal {
+    return 403;
+}
+
+location /api/ {
+    proxy_pass http://backend;
+}
+```
+
+---
+
+## 4. Reverse Proxy
+
+### Basic Proxy
+
+```nginx
+upstream backend {
+    server 127.0.0.1:3000;
+}
+
+server {
+    listen 80;
+    server_name app.example.com;
+
+    location / {
+        proxy_pass http://backend;
+
+        # Pass original client information
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # Timeouts
+        proxy_connect_timeout 5s;
+        proxy_send_timeout 30s;
+        proxy_read_timeout 30s;
+
+        # Buffering
+        proxy_buffering on;
+        proxy_buffer_size 4k;
+        proxy_buffers 8 4k;
+    }
+}
+```
+
+### WebSocket Proxy
+
+```nginx
+location /ws {
+    proxy_pass http://backend;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+
+    # Prevent WebSocket timeout
+    proxy_read_timeout 86400s;
+    proxy_send_timeout 86400s;
+}
+```
+
+### Trailing Slash Behavior
+
+```nginx
+# With trailing slash: /api/ -> http://backend/
+# Strips the matched prefix
+location /api/ {
+    proxy_pass http://backend/;
+}
+# Request: /api/users -> proxied as /users
+
+# Without trailing slash: /api/ -> http://backend/api/
+# Preserves the full URI
+location /api/ {
+    proxy_pass http://backend;
+}
+# Request: /api/users -> proxied as /api/users
+```
+
+---
+
+## 5. SSL/TLS
+
+### Modern TLS Configuration
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name example.com;
+
+    # Certificates
+    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
+
+    # Protocol versions -- TLS 1.2 and 1.3 only
+    ssl_protocols TLSv1.2 TLSv1.3;
+
+    # Cipher suites
+    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
+    ssl_prefer_server_ciphers off;
+
+    # OCSP Stapling -- faster TLS handshake
+    ssl_stapling on;
+    ssl_stapling_verify on;
+    ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem;
+    resolver 1.1.1.1 8.8.8.8 valid=300s;
+    resolver_timeout 5s;
+
+    # Session caching
+    ssl_session_cache shared:SSL:10m;
+    ssl_session_timeout 1d;
+    ssl_session_tickets off;
+
+    # HSTS -- force HTTPS for 2 years
+    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
+}
+```
+
+### Let's Encrypt with Certbot
+
+```nginx
+# HTTP challenge location
+server {
+    listen 80;
+    server_name example.com;
+
+    location /.well-known/acme-challenge/ {
+        root /var/www/certbot;
+    }
+
+    location / {
+        return 301 https://$host$request_uri;
+    }
+}
+```
+
+```bash
+# Obtain certificate
+certbot certonly --webroot -w /var/www/certbot -d example.com -d www.example.com
+
+# Auto-renewal (certbot installs a timer/cron by default)
+certbot renew --dry-run
+
+# Reload nginx after renewal
+certbot renew --deploy-hook "systemctl reload nginx"
+```
+
+---
+
+## 6. Load Balancing
+
+### Upstream Configuration
+
+```nginx
+upstream api_servers {
+    # Round-robin (default)
+    server 10.0.0.1:3000;
+    server 10.0.0.2:3000;
+    server 10.0.0.3:3000;
+
+    # Backup server -- only used when all others are down
+    server 10.0.0.4:3000 backup;
+
+    # Mark a server as permanently down
+    server 10.0.0.5:3000 down;
+
+    # Keepalive connections to backends
+    keepalive 32;
+}
+```
+
+### Load Balancing Algorithms
+
+```nginx
+# Least connections -- send to the server with fewest active connections
+upstream api_servers {
+    least_conn;
+    server 10.0.0.1:3000;
+    server 10.0.0.2:3000;
+}
+
+# IP hash -- same client always goes to the same server (sticky sessions)
+upstream api_servers {
+    ip_hash;
+    server 10.0.0.1:3000;
+    server 10.0.0.2:3000;
+}
+
+# Weighted -- distribute based on server capacity
+upstream api_servers {
+    server 10.0.0.1:3000 weight=3;  # Gets 3x the traffic
+    server 10.0.0.2:3000 weight=1;
+}
+```
+
+### Health Checks (Nginx Plus or OpenResty)
+
+```nginx
+# Passive health checks (open-source Nginx)
+upstream api_servers {
+    server 10.0.0.1:3000 max_fails=3 fail_timeout=30s;
+    server 10.0.0.2:3000 max_fails=3 fail_timeout=30s;
+}
+```
+
+---
+
+## 7. Caching
+
+### Proxy Cache
+
+```nginx
+# Define cache zone in http block
+proxy_cache_path /var/cache/nginx/api
+    levels=1:2
+    keys_zone=api_cache:10m     # 10MB for keys (approx 80,000 keys)
+    max_size=1g                 # 1GB on disk
+    inactive=60m                # Remove items unused for 60 minutes
+    use_temp_path=off;
+
+server {
+    location /api/ {
+        proxy_pass http://backend;
+        proxy_cache api_cache;
+        proxy_cache_valid 200 10m;      # Cache 200 responses for 10 minutes
+        proxy_cache_valid 404 1m;       # Cache 404 responses for 1 minute
+        proxy_cache_use_stale error timeout updating http_500 http_502 http_503;
+        proxy_cache_lock on;            # Only one request populates the cache
+        proxy_cache_key "$scheme$request_method$host$request_uri";
+
+        add_header X-Cache-Status $upstream_cache_status;
+    }
+}
+```
+
+### Static File Caching
+
+```nginx
+location /static/ {
+    root /var/www;
+    expires 365d;
+    add_header Cache-Control "public, immutable";
+    access_log off;
+}
+
+# Hashed filenames (e.g., app.abc123.js) -- cache forever
+location ~* \.[a-f0-9]{8,}\.(js|css|png|jpg|svg|woff2)$ {
+    root /var/www;
+    expires max;
+    add_header Cache-Control "public, immutable";
+    access_log off;
+}
+```
+
+---
+
+## 8. Compression
+
+```nginx
+# Enable gzip in http block
+gzip on;
+gzip_vary on;
+gzip_proxied any;
+gzip_comp_level 5;          # 1-9, balance between CPU and compression ratio
+gzip_min_length 256;        # Do not compress tiny responses
+gzip_types
+    text/plain
+    text/css
+    text/xml
+    text/javascript
+    application/javascript
+    application/json
+    application/xml
+    application/rss+xml
+    image/svg+xml;
+
+# Brotli (requires ngx_brotli module)
+brotli on;
+brotli_comp_level 6;
+brotli_types
+    text/plain
+    text/css
+    text/xml
+    text/javascript
+    application/javascript
+    application/json
+    application/xml
+    image/svg+xml;
+```
+
+---
+
+## 9. Rate Limiting
+
+```nginx
+# Define rate limit zones in http block
+limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;
+limit_req_zone $binary_remote_addr zone=login_limit:10m rate=1r/s;
+
+server {
+    # API rate limiting -- allow burst of 20 with no delay for first 10
+    location /api/ {
+        limit_req zone=api_limit burst=20 nodelay;
+        limit_req_status 429;
+        proxy_pass http://backend;
+    }
+
+    # Strict rate limiting on login endpoint
+    location /api/auth/login {
+        limit_req zone=login_limit burst=5;
+        limit_req_status 429;
+        proxy_pass http://backend;
+    }
+}
+```
+
+### Connection Limiting
+
+```nginx
+limit_conn_zone $binary_remote_addr zone=conn_limit:10m;
+
+server {
+    location /downloads/ {
+        limit_conn conn_limit 5;     # Max 5 concurrent connections per IP
+        limit_rate 500k;             # Limit bandwidth to 500KB/s per connection
+    }
+}
+```
+
+---
+
+## 10. Security Headers
+
+```nginx
+# Add to every server block (or http block for global)
+add_header X-Content-Type-Options "nosniff" always;
+add_header X-Frame-Options "DENY" always;
+add_header X-XSS-Protection "0" always;
+add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
+add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; connect-src 'self' https://api.example.com; frame-ancestors 'none'; base-uri 'self'; form-action 'self';" always;
+
+# HSTS (only on HTTPS server blocks)
+add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
+```
+
+---
+
+## 11. Access Control
+
+```nginx
+# IP-based access control
+location /admin/ {
+    allow 10.0.0.0/8;
+    allow 192.168.1.0/24;
+    deny all;
+    proxy_pass http://admin_backend;
+}
+
+# Basic authentication
+location /staging/ {
+    auth_basic "Staging Environment";
+    auth_basic_user_file /etc/nginx/.htpasswd;
+    proxy_pass http://staging_backend;
+}
+
+# Block specific user agents
+if ($http_user_agent ~* (bot|crawler|spider)) {
+    return 403;
+}
+
+# Block access to hidden files
+location ~ /\. {
+    deny all;
+    access_log off;
+    log_not_found off;
+}
+```
+
+```bash
+# Create htpasswd file
+# Install: apt install apache2-utils
+htpasswd -c /etc/nginx/.htpasswd admin
+```
+
+---
+
+## 12. Logging
+
+### Custom Log Formats
+
+```nginx
+# Define in http block
+log_format main '$remote_addr - $remote_user [$time_local] '
+                '"$request" $status $body_bytes_sent '
+                '"$http_referer" "$http_user_agent"';
+
+log_format json escape=json '{'
+    '"time": "$time_iso8601",'
+    '"remote_addr": "$remote_addr",'
+    '"request_method": "$request_method",'
+    '"request_uri": "$request_uri",'
+    '"status": $status,'
+    '"body_bytes_sent": $body_bytes_sent,'
+    '"request_time": $request_time,'
+    '"upstream_response_time": "$upstream_response_time",'
+    '"http_user_agent": "$http_user_agent",'
+    '"http_referer": "$http_referer"'
+'}';
+
+access_log /var/log/nginx/access.log json;
+error_log /var/log/nginx/error.log warn;
+```
+
+### Conditional Logging
+
+```nginx
+# Do not log health checks
+map $request_uri $loggable {
+    ~*^/health  0;
+    ~*^/ready   0;
+    default     1;
+}
+
+access_log /var/log/nginx/access.log main if=$loggable;
+
+# Do not log static file access
+location /static/ {
+    access_log off;
+}
+```
+
+---
+
+## 13. HTTP/2 and HTTP/3
+
+```nginx
+# HTTP/2 (widely supported)
+server {
+    listen 443 ssl http2;
+    listen [::]:443 ssl http2;
+    # ...
+
+    # HTTP/2 push (deprecated in most browsers, avoid)
+    # Use 103 Early Hints instead
+    location / {
+        add_header Link "</style.css>; rel=preload; as=style";
+        proxy_pass http://backend;
+    }
+}
+
+# HTTP/3 (QUIC -- requires Nginx 1.25+ with quic module)
+server {
+    listen 443 ssl;
+    listen 443 quic reuseport;
+
+    http2 on;
+    http3 on;
+
+    # Advertise HTTP/3 support
+    add_header Alt-Svc 'h3=":443"; ma=86400' always;
+
+    ssl_certificate     /etc/ssl/certs/example.com.crt;
+    ssl_certificate_key /etc/ssl/private/example.com.key;
+
+    # Required for QUIC
+    ssl_early_data on;
+}
+```
+
+---
+
+## 14. Rewrites and Redirects
+
+```nginx
+# Permanent redirect (301)
+location /old-page {
+    return 301 /new-page;
+}
+
+# Redirect with query string preservation
+location /search {
+    return 301 /find$is_args$args;
+}
+
+# Rewrite (internal -- URL changes but client does not see it)
+rewrite ^/blog/(\d{4})/(\d{2})/(.+)$ /posts?year=$1&month=$2&slug=$3 last;
+
+# Rewrite with redirect
+rewrite ^/legacy/(.*)$ /modern/$1 permanent;  # 301
+rewrite ^/temp/(.*)$ /current/$1 redirect;     # 302
+
+# Canonical domain redirect
+server {
+    listen 80;
+    server_name www.example.com;
+    return 301 https://example.com$request_uri;
+}
+```
+
+---
+
+## 15. try_files
+
+```nginx
+# Single Page Application (SPA) -- serve index.html for all routes
+location / {
+    root /var/www/app;
+    try_files $uri $uri/ /index.html;
+}
+
+# Static files first, then proxy to backend
+location / {
+    root /var/www/public;
+    try_files $uri @backend;
+}
+
+location @backend {
+    proxy_pass http://app_server;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+}
+
+# Custom 404 page
+location / {
+    root /var/www;
+    try_files $uri $uri/ =404;
+    error_page 404 /404.html;
+}
+```
+
+---
+
+## 16. Nginx as API Gateway
+
+```nginx
+# Rate limiting, authentication, and routing in one place
+upstream auth_service {
+    server 127.0.0.1:4000;
+    keepalive 16;
+}
+
+upstream user_service {
+    server 127.0.0.1:4001;
+    keepalive 16;
+}
+
+upstream order_service {
+    server 127.0.0.1:4002;
+    keepalive 16;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name api.example.com;
+
+    # Global rate limit
+    limit_req zone=api_limit burst=50 nodelay;
+
+    # CORS headers
+    add_header Access-Control-Allow-Origin "https://app.example.com" always;
+    add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
+    add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
+
+    # Preflight requests
+    if ($request_method = OPTIONS) {
+        add_header Access-Control-Allow-Origin "https://app.example.com";
+        add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS";
+        add_header Access-Control-Allow-Headers "Authorization, Content-Type";
+        add_header Access-Control-Max-Age 86400;
+        return 204;
+    }
+
+    # Route to microservices
+    location /api/v1/auth/ {
+        proxy_pass http://auth_service/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    location /api/v1/users/ {
+        proxy_pass http://user_service/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    location /api/v1/orders/ {
+        proxy_pass http://order_service/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    # Request size limit for file uploads
+    location /api/v1/uploads/ {
+        client_max_body_size 50m;
+        proxy_pass http://user_service/uploads/;
+    }
+}
+```
+
+---
+
+## 17. Performance Tuning
+
+```nginx
+# nginx.conf -- main context
+worker_processes auto;          # One worker per CPU core
+worker_rlimit_nofile 65535;     # Max open files per worker
+
+events {
+    worker_connections 4096;    # Max connections per worker
+    multi_accept on;            # Accept multiple connections at once
+    use epoll;                  # Linux optimal event method
+}
+
+http {
+    # Sendfile -- bypass user space for static files
+    sendfile on;
+    tcp_nopush on;              # Send headers and file in one packet
+    tcp_nodelay on;             # Disable Nagle's algorithm for small packets
+
+    # Timeouts
+    keepalive_timeout 65;
+    keepalive_requests 1000;
+    client_body_timeout 12;
+    client_header_timeout 12;
+    send_timeout 10;
+
+    # Buffers
+    client_body_buffer_size 16k;
+    client_header_buffer_size 1k;
+    client_max_body_size 8m;
+    large_client_header_buffers 4 8k;
+
+    # File descriptor cache
+    open_file_cache max=1000 inactive=20s;
+    open_file_cache_valid 30s;
+    open_file_cache_min_uses 2;
+    open_file_cache_errors on;
+
+    # MIME types
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+
+    # Logging
+    access_log /var/log/nginx/access.log main buffer=16k flush=5s;
+    error_log /var/log/nginx/error.log warn;
+}
+```
+
+---
+
+## 18. Anti-Patterns
+
+### NEVER
+
+- Edit configuration without running `nginx -t` before reloading
+- Use `if` blocks in location context for anything other than `return` or `rewrite` -- it causes subtle bugs
+- Hardcode backend addresses in location blocks -- use upstream blocks
+- Serve static files through a proxy when Nginx can serve them directly
+- Disable access logging in production -- you need it for debugging
+- Use `ssl on` (deprecated) -- use `listen 443 ssl` instead
+- Run Nginx as root for worker processes -- only the master process needs root
+- Skip security headers -- add them in every server block
+- Use self-signed certificates in production -- use Let's Encrypt
+- Ignore the `always` parameter on `add_header` -- without it, headers are not added to error responses
+
+### ALWAYS
+
+- Run `nginx -t` before `nginx -s reload`
+- Use `upstream` blocks for backend servers
+- Enable gzip/brotli compression for text-based content
+- Set appropriate `client_max_body_size` for each endpoint
+- Use `try_files` for SPA routing instead of nested if/rewrite blocks
+- Set `keepalive` connections to upstream backends
+- Include security headers on every response
+- Log in structured JSON format for production
+- Configure SSL with modern cipher suites and TLS 1.2+
+- Monitor error logs and upstream response times
+
+---
+
+## 19. Quick Reference
+
+```bash
+# Test configuration
+nginx -t
+
+# Reload configuration (graceful -- no downtime)
+nginx -s reload
+
+# Stop (graceful)
+nginx -s quit
+
+# Stop (immediate)
+nginx -s stop
+
+# Show compiled modules
+nginx -V
+
+# Show active configuration
+nginx -T
+
+# Check which process is listening
+ss -tlnp | grep :80
+```