Sankofa/docs/configs/nginx/README.md

# Nginx Proxy Configuration Guide

## Overview
This guide covers configuring the Nginx Proxy VM for SMOM-DBIS-138 deployment to handle SSL/TLS termination and routing.

## Prerequisites
- Nginx Proxy VM deployed and running
- SSH access to the VM
- Domain names configured in DNS
- Cloudflare account (for DNS management)

## Quick Start

### 1. Get VM IP Address
```bash
kubectl get proxmoxvm nginx-proxy-vm -n default -o jsonpath='{.status.ipAddress}'
```

### 2. SSH into the VM
```bash
ssh admin@<vm-ip-address>
```

### 3. Install SSL Certificates
```bash
# Install certbot if not already installed
sudo apt-get update
sudo apt-get install -y certbot python3-certbot-nginx

# Obtain SSL certificate
sudo certbot --nginx -d your-domain.com -d www.your-domain.com
```

### 4. Configure Backend Services

Create configuration files in `/etc/nginx/sites-available/`:

#### Example: SMOM Services
```nginx
server {
    listen 80;
    listen [::]:80;
    server_name smom-api.sankofa.nexus;
    
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name smom-api.sankofa.nexus;
    
    ssl_certificate /etc/letsencrypt/live/smom-api.sankofa.nexus/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/smom-api.sankofa.nexus/privkey.pem;
    
    location / {
        proxy_pass http://smom-services:8080;
        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;
    }
}
```

### 5. Enable Configuration
```bash
# Create symlink
sudo ln -s /etc/nginx/sites-available/smom-api /etc/nginx/sites-enabled/

# Test configuration
sudo nginx -t

# Reload nginx
sudo systemctl reload nginx
```

## Configuration Files

### Main Nginx Configuration
Location: `/etc/nginx/nginx.conf`

Key settings:
- Worker processes: `auto` (matches CPU cores)
- Worker connections: `1024`
- Gzip compression: Enabled
- SSL protocols: TLSv1.2, TLSv1.3

### Site Configurations
Location: `/etc/nginx/sites-available/`

Each service should have its own configuration file:
- `smom-api.conf` - API services
- `smom-blockscout.conf` - Blockscout explorer
- `smom-monitoring.conf` - Monitoring dashboards
- `smom-rpc.conf` - RPC endpoints

## SSL/TLS Configuration

### Automatic Certificate Renewal
Certbot automatically sets up renewal. Verify with:
```bash
sudo certbot renew --dry-run
```

### Manual Certificate Renewal
```bash
sudo certbot renew
sudo systemctl reload nginx
```

## Security Headers

All configurations should include:
```nginx
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
```

## Load Balancing

For multiple backend instances:
```nginx
upstream smom_services {
    least_conn;
    server smom-services-01:8080;
    server smom-services-02:8080;
    server smom-services-03:8080;
}

server {
    location / {
        proxy_pass http://smom_services;
    }
}
```

## Monitoring

### Access Logs
```bash
tail -f /var/log/nginx/access.log
```

### Error Logs
```bash
tail -f /var/log/nginx/error.log
```

### Status Check
```bash
curl http://localhost/nginx_status
```

## Troubleshooting

### Test Configuration
```bash
sudo nginx -t
```

### Check Nginx Status
```bash
sudo systemctl status nginx
```

### View Active Connections
```bash
sudo netstat -tulpn | grep nginx
```

### Check SSL Certificate
```bash
sudo certbot certificates
```

## Next Steps
1. Configure all backend services
2. Set up monitoring and alerting
3. Configure rate limiting
4. Set up failover/backup proxy