NGINX: AI-Optimized Technical Reference

Configuration That Actually Works in Production

Core Architecture

• Event-driven model: One worker process handles thousands of connections using epoll (Linux) or kqueue (FreeBSD)
• Worker processes: Should match CPU cores exactly
• Connection handling: 10,000 idle connections use only 2.5MB RAM (vs Apache's 150-200MB)
• Performance reality: 200k req/sec typical in production (not the 500k marketing claims)

Critical Performance Settings

worker_processes auto;  # Match CPU cores
worker_connections 1024;  # Must not exceed ulimit -n
sendfile on;  # Zero-copy file transfers
proxy_buffers 8 16k;  # Tune for workload
client_max_body_size 10m;  # Set appropriately

Connection Limits That Will Break You

• File descriptors: Increase ulimit -n before tuning worker_connections
• Backend connections: 40,000-50,000 new connections/second typical limit
• Database proxying: MySQL defaults to 151 connections, PostgreSQL to 100
• Breaking point: Connection limits hit before CPU/memory limits

Resource Requirements

Time Investments

• Basic setup: 30 minutes for simple reverse proxy
• SSL configuration: 2-4 hours including certificate debugging
• Load balancing tuning: 1-2 days for complex upstreams
• Cache configuration: 4-8 hours debugging cache keys and invalidation
• Production debugging: Expect 2-6 hour incidents for misconfigured routing

Expertise Requirements

• Beginner: Can handle basic static serving and simple proxying
• Intermediate: Required for SSL, caching, and load balancing
• Expert: Needed for microservices routing, njs scripting, performance optimization
• Critical skill: Regex debugging (will consume significant time)

Infrastructure Costs

• Hardware: Scales efficiently, minimal resource requirements
• Operational overhead: Moderate for basic setups, high for complex routing
• Support costs: Free version sufficient for most use cases
• NGINX Plus: $670M acquisition value indicates enterprise pricing

Critical Warnings and Failure Modes

SSL Termination Disasters

• Certificate path errors: Cryptic "SSL_CTX_use_PrivateKey_file() failed" messages
• File permissions: NGINX won't indicate it can't read private keys
• SNI overlaps: Configurations that overlap will break unexpectedly
• OCSP stapling: External HTTP requests can slow SSL handshakes if responder is slow

Configuration Hell Scenarios

• DNS in upstreams: Never use hostnames in upstream blocks (causes 30-second response times)
• Cache key debugging: Trailing slashes and Vary headers create separate cache entries
• Rate limiting: Off-by-one errors in burst settings block legitimate users or allow attacks
• Map directive scope: Variables are evaluated per-request, not per-location (poorly documented)

Load Balancing Gotchas

• Health checks: Basic checks only verify port open, not application health
• Session persistence: IP hash needed when stateless design isn't implemented
• Connection pooling: Upstream health checks consume backend connection limits
• Database proxying: Health checks establish connections but don't validate database functionality

Microservices Routing Nightmares

• Service discovery: No native dynamic discovery, requires external systems
• Request tracing: Debugging traffic through 47 services becomes impossible
• Circuit breakers: Work but debugging failures across services is complex
• BFF in config: Building Backend-for-Frontend in NGINX configs is maintenance hell

Implementation Reality vs Documentation

What Official Docs Don't Tell You

• Mirror module risk: Don't point traffic mirroring at production databases
• njs memory leaks: JavaScript errors affect entire worker process
• Auth request latency: Every protected request waits for external auth validation
• Cache invalidation: Geographic differences in content freshness are normal but hard to explain

Community Wisdom

• F5 acquisition significance: $670M indicates serious enterprise value
• Netflix early adoption: Switched because Apache couldn't handle streaming load
• Market share reality: 21.2% of all websites, 33.6% of high-traffic sites
• Performance benchmarks: Lab conditions vs real-world performance gap is significant

Migration Pain Points

• Apache .htaccess: No equivalent, requires config rewrite
• Module ecosystem: Smaller than Apache's extensive module library
• Configuration approach: Declarative blocks vs flexible directives requires learning curve
• Legacy integration: Header transformations for old applications are complex

Decision Criteria

Choose NGINX When

• High traffic: >10,000 concurrent connections
• Static content heavy: Documentation, media, CDN scenarios
• Microservices architecture: API gateway requirements
• Performance critical: Response time and throughput matter
• Modern applications: HTTP/2, SSL termination important

Avoid NGINX When

• Legacy PHP applications: Depend on .htaccess mod_rewrite magic
• Complex Apache modules: Required functionality not available in NGINX
• Limited expertise: Team lacks time to learn declarative configuration
• Simple static sites: Apache or simpler solutions sufficient

Worth the Cost Despite

• Configuration complexity: Declarative approach has learning curve
• Debugging difficulty: Error messages often cryptic
• Limited dynamic reconfiguration: Requires reloads for most changes
• Regex maintenance: Complex routing rules become maintenance burden

Comparative Performance Expectations

Scenario	NGINX	Apache	Reality Check
Static files	200k req/sec	50k req/sec	Your hardware varies
SSL handshakes	High performance	Standard	OCSP latency matters
Memory per 10k conn	2.5MB	150MB	Idle connections only
New connections/sec	40-50k	10-20k	Backend response time critical
Configuration time	Minutes	Hours	For equivalent functionality

Breaking Points and Limits

File Descriptor Exhaustion

• Symptom: Connection refused errors under load
• Cause: Default ulimit too low for worker_connections setting
• Solution: Increase system limits before NGINX limits
• Impact: Service unavailable until restart

Cache Disk Space

• Symptom: Proxy cache fills disk, service stops
• Cause: No automatic cache cleanup configuration
• Solution: Configure cache max_size and inactive parameters
• Impact: Complete service outage

Backend Connection Saturation

• Symptom: Database connection limit errors
• Cause: Health checks plus real traffic exceed database limits
• Solution: Tune upstream health check frequency and connection pooling
• Impact: Application errors, data consistency issues

SSL Certificate Expiration

• Symptom: Browser security warnings, connection failures
• Cause: Automated renewal failures or wrong file permissions
• Solution: Monitor certificate expiration, test renewal automation
• Impact: Complete site unavailability for HTTPS traffic