proxmox/docs/09-troubleshooting/NGINX_RPC_2500_CONFIGURATION.md

Nginx Configuration for RPC-01 (VMID 2500)

Last Updated: 2026-01-31
Document Version: 1.0
Status: Active Documentation

Container: besu-rpc-1 (Core RPC Node)
VMID: 2500
IP: 192.168.11.250

---

✅ Installation Complete

Nginx has been installed and configured as a reverse proxy for Besu RPC endpoints.

---

📋 Configuration Summary

Ports Configured

Port	Protocol	Purpose	Backend
80	HTTP	HTTP to HTTPS redirect	N/A
443	HTTPS	HTTP RPC API	localhost:8545
8443	HTTPS	WebSocket RPC API	localhost:8546

Server Names

• besu-rpc-1
• 192.168.11.250
• rpc-core.besu.local
• rpc-core.chainid138.local
• rpc-core-ws.besu.local (WebSocket only)
• rpc-core-ws.chainid138.local (WebSocket only)

---

🔧 Configuration Details

HTTP RPC (Port 443)

Location: /etc/nginx/sites-available/rpc-core

Features:

• SSL/TLS encryption (TLS 1.2 and 1.3)
• Proxies to Besu HTTP RPC on port 8545
• Extended timeouts (300s) for RPC calls
• Disabled buffering for real-time responses
• CORS headers for web application access
• Security headers (HSTS, X-Frame-Options, etc.)
• Health check endpoint at /health
• Metrics endpoint at /metrics (proxies to port 9545)

WebSocket RPC (Port 8443)

Features:

• SSL/TLS encryption
• Proxies to Besu WebSocket RPC on port 8546
• WebSocket upgrade headers
• Extended timeouts (86400s) for persistent connections
• Health check endpoint at /health

SSL Certificate

Location: /etc/nginx/ssl/

• Certificate: /etc/nginx/ssl/rpc.crt
• Private Key: /etc/nginx/ssl/rpc.key
• Type: Self-signed (valid for 10 years)
• CN: besu-rpc-1

Note: Replace with Let's Encrypt certificate for production use.

---

🧪 Testing

Test Health Endpoint

# From container
pct exec 2500 -- curl -k https://localhost:443/health

# From external
curl -k https://192.168.11.250:443/health

Expected: healthy

Test HTTP RPC

# From container
pct exec 2500 -- curl -k -X POST https://localhost:443 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

# From external
curl -k -X POST https://192.168.11.250:443 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Expected: JSON response with current block number

Test WebSocket RPC

# Using wscat (if installed)
wscat -c wss://192.168.11.250:8443

# Or using websocat
websocat wss://192.168.11.250:8443

Test Metrics Endpoint

curl -k https://192.168.11.250:443/metrics

---

📊 Log Files

Access Logs:

• HTTP RPC: /var/log/nginx/rpc-core-http-access.log
• WebSocket RPC: /var/log/nginx/rpc-core-ws-access.log

Error Logs:

• HTTP RPC: /var/log/nginx/rpc-core-http-error.log
• WebSocket RPC: /var/log/nginx/rpc-core-ws-error.log

View Logs:

# HTTP access
pct exec 2500 -- tail -f /var/log/nginx/rpc-core-http-access.log

# HTTP errors
pct exec 2500 -- tail -f /var/log/nginx/rpc-core-http-error.log

# WebSocket access
pct exec 2500 -- tail -f /var/log/nginx/rpc-core-ws-access.log

---

🔒 Security Features

SSL/TLS Configuration

• Protocols: TLSv1.2, TLSv1.3
• Ciphers: Strong ciphers only (ECDHE, DHE)
• Session Cache: Enabled (10m)
• Session Timeout: 10 minutes

Security Headers

• Strict-Transport-Security: 1 year HSTS
• X-Frame-Options: SAMEORIGIN
• X-Content-Type-Options: nosniff
• X-XSS-Protection: 1; mode=block

CORS Configuration

• Access-Control-Allow-Origin: * (allows all origins)
• Access-Control-Allow-Methods: GET, POST, OPTIONS
• Access-Control-Allow-Headers: Content-Type, Authorization

Note: Adjust CORS settings based on your security requirements.

---

🔧 Management Commands

Check Nginx Status

pct exec 2500 -- systemctl status nginx

Test Configuration

pct exec 2500 -- nginx -t

Reload Configuration

pct exec 2500 -- systemctl reload nginx

Restart Nginx

pct exec 2500 -- systemctl restart nginx

View Configuration

pct exec 2500 -- cat /etc/nginx/sites-available/rpc-core

---

🔄 Updating Configuration

Edit Configuration

pct exec 2500 -- nano /etc/nginx/sites-available/rpc-core

After Editing

# Test configuration
pct exec 2500 -- nginx -t

# If test passes, reload
pct exec 2500 -- systemctl reload nginx

---

🔐 SSL Certificate Management

Current Certificate

Type: Self-signed
Valid For: 10 years
Location: /etc/nginx/ssl/

Replace with Let's Encrypt

1. Install Certbot:

pct exec 2500 -- apt-get install -y certbot python3-certbot-nginx

2. Obtain Certificate:

pct exec 2500 -- certbot --nginx -d rpc-core.besu.local -d rpc-core.chainid138.local

3. Auto-renewal (certbot sets this up automatically):

pct exec 2500 -- certbot renew --dry-run

---

🌐 Integration with nginx-proxy-manager

If using nginx-proxy-manager (VMID 105) as a central proxy:

Configuration:

• Domain: rpc-core.besu.local or rpc-core.chainid138.local
• Forward to: 192.168.11.250:443 (HTTPS)
• SSL: Handle at nginx-proxy-manager level (or pass through)
• Websockets: Enabled

Note: You can also forward to port 8545 directly and let nginx-proxy-manager handle SSL.

---

📈 Performance Tuning

Current Settings

• Proxy Timeouts: 300s (5 minutes)
• WebSocket Timeouts: 86400s (24 hours)
• Client Max Body Size: 10M
• Buffering: Disabled (for real-time RPC)

Adjust if Needed

Edit /etc/nginx/sites-available/rpc-core and adjust:

• proxy_read_timeout
• proxy_send_timeout
• proxy_connect_timeout
• client_max_body_size

---

🐛 Troubleshooting

Nginx Not Starting

# Check configuration syntax
pct exec 2500 -- nginx -t

# Check error logs
pct exec 2500 -- journalctl -u nginx -n 50

# Check for port conflicts
pct exec 2500 -- ss -tlnp | grep -E ':80|:443|:8443'

RPC Not Responding

# Check if Besu RPC is running
pct exec 2500 -- ss -tlnp | grep 8545

# Test direct connection
pct exec 2500 -- curl -X POST http://localhost:8545 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

# Check Nginx error logs
pct exec 2500 -- tail -50 /var/log/nginx/rpc-core-http-error.log

SSL Certificate Issues

# Check certificate
pct exec 2500 -- openssl x509 -in /etc/nginx/ssl/rpc.crt -text -noout

# Verify certificate matches key
pct exec 2500 -- openssl x509 -noout -modulus -in /etc/nginx/ssl/rpc.crt | openssl md5
pct exec 2500 -- openssl rsa -noout -modulus -in /etc/nginx/ssl/rpc.key | openssl md5

---

✅ Verification Checklist

• Nginx installed
• SSL certificate generated
• Configuration file created
• Site enabled
• Nginx service active
• Port 80 listening (HTTP redirect)
• Port 443 listening (HTTPS RPC)
• Port 8443 listening (HTTPS WebSocket)
• Configuration test passed
• RPC endpoint responding through Nginx
• Health check endpoint working

---

📚 Related Documentation

• Nginx Architecture for RPC Nodes
• RPC Node Types Architecture
• Cloudflare Nginx Integration

---

Configuration Date: $(date)
Status: ✅ OPERATIONAL