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

```bash
# Ubuntu/Debian
sudo apt update
sudo apt install nginx

# CentOS/RHEL
sudo yum install nginx

# Verify installation
nginx -v
```

### 2. Backup Default Configuration

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

### 3. Copy Configuration File

```bash
sudo cp nginx.conf /etc/nginx/nginx.conf
```

### 4. Create SSL Certificate Directories

```bash
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:

```bash
# 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:

```bash
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

```bash
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

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

### 9. Start and Enable Nginx

```bash
sudo systemctl start nginx
sudo systemctl enable nginx
sudo systemctl status nginx
```

### 10. Verify Services

```bash
# 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:

```bash
# 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

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

### View Error Logs

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

### Test Specific Configuration

```bash
# 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:

```bash
# 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:

```bash
# 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:

```nginx
worker_processes auto;  # Auto-detects CPU cores
```

### Worker Connections

Adjust based on expected load:

```nginx
worker_connections 2048;  # Increase for high traffic
```

### File Descriptors

Increase system limits:

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

## Backup and Recovery

### Backup Configuration

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

### Restore Configuration

```bash
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