NGINX Configuration

🌐 What NGINX Does for VoP

NGINX acts as your security gateway and performance booster:

Internet → NGINX → VoP API → Database
   ↓        ↓        ↓         ↓
  SSL    Security  Business  Encrypted
       Validation   Logic     Storage

🔒 Security Features

• SSL/TLS termination - Handles all encryption
• Client certificate validation - Blocks unauthorized access
• Rate limiting - Prevents abuse and DDoS
• Security headers - Protects against common attacks

⚡ Performance Features

• Load balancing - Distributes traffic across multiple VoP instances
• Caching - Speeds up responses
• Compression - Reduces bandwidth usage
• Connection pooling - Efficient resource usage

Automatic Setup

🚀 One-Command Configuration

# NGINX is automatically configured when you run:
make setup-epc-complete

# This sets up:
# ✅ SSL certificates
# ✅ NGINX configuration
# ✅ Security headers
# ✅ Rate limiting
# ✅ Load balancing

📁 Configuration Files

nginx/
├── nginx.conf          # Main configuration
├── ssl.conf           # SSL settings
├── security.conf      # Security headers
└── upstream.conf      # Load balancing

Key Configuration Highlights

🔐 SSL Security (Bank-Grade)

# TLS 1.3+ only (latest security)
ssl_protocols TLSv1.2 TLSv1.3;

# Client certificate required (mTLS)
ssl_client_certificate /etc/nginx/certs/ca.crt;
ssl_verify_client on;

# Strong encryption ciphers
ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;

🛡️ Security Headers

# Prevent clickjacking
add_header X-Frame-Options DENY always;

# Prevent MIME type sniffing
add_header X-Content-Type-Options nosniff always;

# Force HTTPS for 1 year
add_header Strict-Transport-Security "max-age=31536000" always;

# Content Security Policy
add_header Content-Security-Policy "default-src 'self'" always;

⚡ Rate Limiting

# Limit API requests to prevent abuse
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

# Allow burst of 20 requests, then rate limit
limit_req zone=api burst=20 nodelay;

Testing NGINX Setup

✅ 1. Check NGINX is Running

# Check NGINX status
docker-compose ps nginx

# Should show: Up and healthy

✅ 2. Test SSL Configuration

# Test HTTPS endpoint
curl -k https://localhost:443/health

# Expected: {"status": "healthy"}

✅ 3. Test Client Certificate Authentication

# With client certificate (should work)
curl --cert certs/client/client.crt \
     --key certs/client/client.key \
     https://localhost:443/health

# Without client certificate (should fail)
curl https://localhost:443/health
# Expected: 403 Forbidden

✅ 4. Test Rate Limiting

# Send many requests quickly
for i in {1..25}; do
  curl -s -o /dev/null -w "%{http_code}\n" \
    --cert certs/client/client.crt \
    --key certs/client/client.key \
    https://localhost:443/health
done

# Expected: First 20 return 200, then 429 (rate limited)

Common NGINX Commands

🔧 Service Management

# Start NGINX
docker-compose up -d nginx

# Stop NGINX
docker-compose stop nginx

# Restart NGINX
docker-compose restart nginx

# Reload configuration (no downtime)
docker-compose exec nginx nginx -s reload

📊 Monitoring

# View NGINX logs
docker-compose logs -f nginx

# Check NGINX status
curl http://localhost:8080/nginx-status

# Test configuration syntax
docker-compose exec nginx nginx -t

🔍 SSL Testing

# Test SSL configuration
openssl s_client -connect localhost:443 -servername localhost

# Check certificate details
openssl s_client -connect localhost:443 -showcerts

# Test specific TLS version
openssl s_client -connect localhost:443 -tls1_3

Load Balancing (Multiple VoP Instances)

📈 Scale VoP Service

docker-compose.yml

services:
  vop-service:
    deploy:
      replicas: 3  # Run 3 VoP instances

⚖️ NGINX Load Balancing

# Automatically configured upstream
upstream vop_backend {
    least_conn;  # Route to least busy instance
    server vop-service-1:8443;
    server vop-service-2:8443;
    server vop-service-3:8443;
}

Performance Optimization

🚀 Built-in Optimizations

• HTTP/2 - Faster connection handling
• Gzip compression - Reduces response size by 70%
• Keep-alive connections - Reuses connections efficiently
• Static file caching - Serves files directly from memory

📊 Performance Metrics

# Expected performance:
# - Response time: < 100ms (NGINX overhead)
# - Throughput: 10,000+ requests/second
# - SSL handshake: < 50ms
# - Memory usage: 10-50MB

Security Features

🔒 Client Certificate Validation

# Only clients with valid certificates can access
ssl_verify_client on;
ssl_verify_depth 2;

# Certificate information passed to VoP API
proxy_set_header X-Client-Cert $ssl_client_cert;
proxy_set_header X-Client-Verify $ssl_client_verify;

🛡️ DDoS Protection

# Rate limiting per IP
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

# Rate limiting per client certificate
limit_req_zone $ssl_client_s_dn zone=client_cert:10m rate=100r/s;

# Connection limiting
limit_conn_zone $binary_remote_addr zone=conn_limit_per_ip:10m;
limit_conn conn_limit_per_ip 10;

Troubleshooting

🚫 NGINX Won’t Start

# Check configuration syntax
docker-compose exec nginx nginx -t

# Check logs for errors
docker-compose logs nginx

# Common fix: regenerate certificates
make generate-docker-certs
docker-compose restart nginx

🔐 SSL Certificate Errors

# Check certificate validity
openssl x509 -in certs/server/server.crt -noout -dates

# Verify certificate chain
openssl verify -CAfile certs/ca/ca.crt certs/server/server.crt

# Test SSL handshake
openssl s_client -connect localhost:443

🌐 Connection Issues

# Check if NGINX is listening
netstat -tlnp | grep :443

# Test backend connectivity
docker-compose exec nginx curl -k https://vop-service:8443/health

# Check upstream status
curl http://localhost:8080/nginx-status

📈 Performance Issues

# Check NGINX resource usage
docker stats vop-nginx

# Monitor active connections
curl http://localhost:8080/nginx-status

# Check for errors in logs
grep "error" /var/log/nginx/error.log

Custom Configuration

🎛️ Environment-Specific Settings

Development:

# Relaxed security for development
ssl_verify_client optional;
access_log /var/log/nginx/access.log debug;

Production:

# Maximum security for production
ssl_verify_client on;
ssl_protocols TLSv1.3;  # TLS 1.3 only
add_header Strict-Transport-Security "max-age=31536000; preload";

🌍 Custom Domain Setup

# Configure for your domain
make setup-nginx-domain DOMAIN=api.yourcompany.com

# This updates:
# - Server name in NGINX config
# - SSL certificate with your domain
# - DNS configuration examples

Integration Examples

💻 Application Integration

// Your app connects through NGINX
const response = await fetch('https://your-domain.com/api/v1/verify', {
  method: 'POST',
  // NGINX handles SSL termination and client certificates
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ iban, name })
});

☁️ Cloud Load Balancer Integration

# Export NGINX config for cloud load balancers
make export-nginx-config-aws
make export-nginx-config-gcp
make export-nginx-config-azure