gru_emoney_token-factory/nginx-setup.md

Nginx Configuration Setup Guide

This guide explains how to set up and deploy the nginx configuration for the eMoney Token Factory API.

Overview

The nginx configuration handles:

• 10 production domains (5 services × 2 protocols)
• 10 staging domains (5 services × 2 protocols)
• SSL/TLS termination
• Load balancing
• Rate limiting
• Security headers
• Health checks

Prerequisites

• Nginx 1.18+ installed
• SSL certificates for all domains
• Backend services running on specified ports
• Root or sudo access

Installation Steps

1. Install Nginx

# Ubuntu/Debian
sudo apt update
sudo apt install nginx

# CentOS/RHEL
sudo yum install nginx

# Verify installation
nginx -v

2. Backup Default Configuration

sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.backup

3. Copy Configuration File

sudo cp nginx.conf /etc/nginx/nginx.conf

4. Create SSL Certificate Directories

sudo mkdir -p /etc/ssl/certs
sudo mkdir -p /etc/ssl/private
sudo chmod 700 /etc/ssl/private

5. Install SSL Certificates

For each domain, install SSL certificates:

# Production domains
sudo cp api.d-bis.org.crt /etc/ssl/certs/
sudo cp api.d-bis.org.key /etc/ssl/private/
sudo cp api.d-bis.org-chain.crt /etc/ssl/certs/

# Repeat for all domains:
# - mappings.api.d-bis.org
# - webhooks.api.d-bis.org
# - orchestrator.api.d-bis.org
# - packets.api.d-bis.org
# - api-staging.d-bis.org
# - mappings.api-staging.d-bis.org
# - webhooks.api-staging.d-bis.org
# - orchestrator.api-staging.d-bis.org
# - packets.api-staging.d-bis.org

# Set proper permissions
sudo chmod 644 /etc/ssl/certs/*.crt
sudo chmod 600 /etc/ssl/private/*.key

6. Update Upstream Server IPs

Edit /etc/nginx/nginx.conf and replace placeholder IPs with actual backend server IPs:

sudo nano /etc/nginx/nginx.conf

Update these sections:

• upstream rest_api_production - Replace 192.0.2.1:3000
• upstream mapping_service_production - Replace 192.0.2.2:3004
• upstream webhook_service_production - Replace 192.0.2.3:3001
• upstream orchestrator_service_production - Replace 192.0.2.4:3002
• upstream packet_service_production - Replace 192.0.2.5:3003
• All staging upstreams similarly

7. Test Configuration

sudo nginx -t

Expected output:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

8. Create Log Directories

sudo mkdir -p /var/log/nginx
sudo chown nginx:nginx /var/log/nginx

9. Start and Enable Nginx

sudo systemctl start nginx
sudo systemctl enable nginx
sudo systemctl status nginx

10. Verify Services

# Check nginx is listening on ports
sudo netstat -tlnp | grep nginx
# Should show ports 80 and 443

# Test health endpoints
curl -k https://api.d-bis.org/health
curl -k https://mappings.api.d-bis.org/health
curl -k https://webhooks.api.d-bis.org/health
curl -k https://orchestrator.api.d-bis.org/health
curl -k https://packets.api.d-bis.org/health

Configuration Details

Rate Limiting

• API endpoints: 100 requests/minute with burst of 20
• Webhook endpoints: 50 requests/minute with burst of 10
• Staging: Reduced limits (burst of 10 for API, 5 for webhooks)

Upstream Configuration

• Load balancing: Least connections algorithm
• Health checks: Max 3 failures, 30s timeout
• Keepalive: 32 connections per upstream

SSL/TLS

• Protocols: TLSv1.2, TLSv1.3
• Ciphers: Modern, secure cipher suites
• Session cache: 10MB shared cache
• Session timeout: 10 minutes
• OCSP stapling: Enabled

Security Headers

• HSTS: 1 year with subdomains and preload
• X-Frame-Options: DENY
• X-Content-Type-Options: nosniff
• X-XSS-Protection: Enabled
• Referrer-Policy: strict-origin-when-cross-origin
• CSP: Default-src 'self' with script/style exceptions

Timeouts

• Connection: 30 seconds
• Send: 60 seconds (120s for packet service)
• Read: 60 seconds (120s for packet service)
• Keepalive: 65 seconds

Monitoring

Log Locations

• Access log: /var/log/nginx/access.log
• Error log: /var/log/nginx/error.log

Log Rotation

Create /etc/logrotate.d/nginx:

/var/log/nginx/*.log {
    daily
    missingok
    rotate 52
    compress
    delaycompress
    notifempty
    create 0640 nginx adm
    sharedscripts
    postrotate
        [ -f /var/run/nginx.pid ] && kill -USR1 `cat /var/run/nginx.pid`
    endscript
}

Health Check Monitoring

Set up monitoring for health endpoints:

# Example monitoring script
#!/bin/bash
for domain in api.d-bis.org mappings.api.d-bis.org webhooks.api.d-bis.org \
              orchestrator.api.d-bis.org packets.api.d-bis.org; do
    if ! curl -f -s https://$domain/health > /dev/null; then
        echo "ALERT: $domain health check failed"
        # Send alert notification
    fi
done

Troubleshooting

Check Nginx Status

sudo systemctl status nginx
sudo journalctl -u nginx -n 50

View Error Logs

sudo tail -f /var/log/nginx/error.log

Test Specific Configuration

# Test configuration syntax
sudo nginx -t

# Test specific server block
sudo nginx -T | grep -A 50 "server_name api.d-bis.org"

Common Issues

1. SSL certificate errors

   • Verify certificate paths are correct
   • Check certificate permissions (644 for .crt, 600 for .key)
   • Ensure certificate chain is complete

2. 502 Bad Gateway

   • Check backend services are running
   • Verify upstream IPs and ports are correct
   • Check firewall rules allow nginx to reach backends

3. Rate limiting too aggressive

   • Adjust limit_req_zone rates in http block
   • Increase burst values in server blocks

4. Connection timeouts

   • Increase proxy_connect_timeout, proxy_send_timeout, proxy_read_timeout
   • Check backend service response times

Reload Configuration

After making changes:

# Test configuration
sudo nginx -t

# Reload nginx (graceful, no downtime)
sudo nginx -s reload

# Or restart (brief downtime)
sudo systemctl restart nginx

Firewall Configuration

Ensure firewall allows HTTP/HTTPS:

# UFW (Ubuntu)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# firewalld (CentOS/RHEL)
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

Performance Tuning

Worker Processes

Set worker_processes to number of CPU cores:

worker_processes auto;  # Auto-detects CPU cores

Worker Connections

Adjust based on expected load:

worker_connections 2048;  # Increase for high traffic

File Descriptors

Increase system limits:

# Edit /etc/security/limits.conf
nginx soft nofile 65535
nginx hard nofile 65535

Backup and Recovery

Backup Configuration

sudo tar -czf nginx-backup-$(date +%Y%m%d).tar.gz \
    /etc/nginx/nginx.conf \
    /etc/ssl/certs/ \
    /etc/ssl/private/

Restore Configuration

sudo tar -xzf nginx-backup-YYYYMMDD.tar.gz -C /
sudo nginx -t
sudo systemctl reload nginx

Support

For nginx configuration issues, contact: infrastructure@d-bis.org