Using with Nginx

Nginx is the recommended reverse proxy for production Sockudo deployments. This guide shows you how to configure Nginx for optimal WebSocket performance, SSL termination, and load balancing.

Why Use Nginx with Sockudo?

SSL/TLS Termination: Offload SSL processing from Sockudo
Load Balancing: Distribute WebSocket connections across multiple Sockudo nodes
Rate Limiting: Protect against abuse at the proxy layer
Static Content: Serve static files efficiently
Caching: Cache HTTP API responses

Basic Configuration

Minimal WebSocket Proxy

Here’s a minimal Nginx configuration for WebSocket proxying:

http {
    # WebSocket upgrade configuration
    map $http_upgrade $connection_upgrade {
        default upgrade;
        '' close;
    }

    upstream sockudo_backend {
        server localhost:6001;
    }

    server {
        listen 80;
        server_name sockudo.yourdomain.com;

        # WebSocket connections
        location /app/ {
            proxy_pass http://sockudo_backend;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
            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;

            # WebSocket timeouts
            proxy_connect_timeout 60s;
            proxy_send_timeout 60s;
            proxy_read_timeout 300s;

            # Disable buffering for WebSocket
            proxy_buffering off;
        }

        # REST API endpoints
        location /apps/ {
            proxy_pass http://sockudo_backend;
            proxy_http_version 1.1;
            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;
        }
    }
}

Production Configuration

Install Nginx

# Ubuntu/Debian
sudo apt update
sudo apt install nginx

# CentOS/RHEL
sudo yum install nginx

# macOS
brew install nginx

Obtain SSL Certificate

Use Let’s Encrypt for free SSL certificates:

# Install Certbot
sudo apt install certbot python3-certbot-nginx

# Obtain certificate
sudo certbot --nginx -d sockudo.yourdomain.com

Or use your existing certificates:

# Copy certificates to Nginx directory
sudo cp /path/to/cert.pem /etc/nginx/ssl/
sudo cp /path/to/key.pem /etc/nginx/ssl/
sudo chmod 600 /etc/nginx/ssl/key.pem

Create Nginx Configuration

Create /etc/nginx/sites-available/sockudo.conf:

# WebSocket upgrade mapping
map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

# Rate limiting zones
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
limit_req_zone $binary_remote_addr zone=websocket:10m rate=5r/s;

# Upstream Sockudo servers
upstream sockudo_backend {
    least_conn;  # Use least connections algorithm
    server 127.0.0.1:6001 max_fails=3 fail_timeout=30s;
    # Add more Sockudo instances:
    # server 127.0.0.1:6002 max_fails=3 fail_timeout=30s;
    # server 127.0.0.1:6003 max_fails=3 fail_timeout=30s;
    keepalive 32;
}

# HTTP to HTTPS redirect
server {
    listen 80;
    server_name sockudo.yourdomain.com;

    location / {
        return 301 https://$host$request_uri;
    }
}

# Main HTTPS server
server {
    listen 443 ssl http2;
    server_name sockudo.yourdomain.com;

    # SSL Configuration
    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # Security headers
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Frame-Options DENY always;
    add_header X-Content-Type-Options nosniff always;
    add_header X-XSS-Protection "1; mode=block" always;

    # WebSocket connections
    location /app/ {
        limit_req zone=websocket burst=10 nodelay;

        proxy_pass http://sockudo_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        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;

        # WebSocket timeouts
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 300s;  # 5 minutes for long-lived connections

        # Disable buffering
        proxy_buffering off;
    }

    # REST API - Event triggering
    location ~ ^/apps/.*/events$ {
        limit_req zone=api burst=20 nodelay;

        proxy_pass http://sockudo_backend;
        proxy_http_version 1.1;
        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;

        # API timeouts
        proxy_connect_timeout 5s;
        proxy_send_timeout 10s;
        proxy_read_timeout 10s;
    }

    # REST API - Other endpoints
    location ~ ^/apps/ {
        limit_req zone=api burst=50 nodelay;

        proxy_pass http://sockudo_backend;
        proxy_http_version 1.1;
        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;
    }

    # Health check endpoint
    location /up/ {
        proxy_pass http://sockudo_backend;
        proxy_http_version 1.1;
        access_log off;
    }
}

Enable and Test Configuration

# Enable the site
sudo ln -s /etc/nginx/sites-available/sockudo.conf /etc/nginx/sites-enabled/

# Test configuration
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx

Unix Socket Configuration

For optimal performance when Nginx and Sockudo are on the same server, use Unix sockets instead of TCP:

Sockudo Configuration

# Enable Unix socket in Sockudo
UNIX_SOCKET_ENABLED=true
UNIX_SOCKET_PATH=/var/run/sockudo/sockudo.sock
UNIX_SOCKET_PERMISSION_MODE=660

Or in config/config.json:

{
  "unix_socket": {
    "enabled": true,
    "path": "/var/run/sockudo/sockudo.sock",
    "permission_mode": "660"
  }
}

Nginx Configuration

upstream sockudo_backend {
    server unix:/var/run/sockudo/sockudo.sock;
}

server {
    listen 443 ssl http2;
    server_name sockudo.yourdomain.com;

    # ... SSL config ...

    location / {
        proxy_pass http://sockudo_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Benefits:

~20-30% lower latency (no TCP/IP stack overhead)
Better security (no network exposure)
Simplified deployment (no port conflicts)

Load Balancing Multiple Nodes

Configuration

upstream sockudo_backend {
    # Use IP hash for sticky sessions (recommended for WebSocket)
    ip_hash;
    
    server sockudo-1.internal:6001 max_fails=3 fail_timeout=30s weight=1;
    server sockudo-2.internal:6001 max_fails=3 fail_timeout=30s weight=1;
    server sockudo-3.internal:6001 max_fails=3 fail_timeout=30s weight=1;
    
    keepalive 64;  # Keep connections alive to backend
}

Load Balancing Algorithms

Algorithm	Configuration	Best For
IP Hash	`ip_hash;`	WebSocket (sticky sessions)
Least Connections	`least_conn;`	Balanced distribution
Round Robin	Default	Simple equal distribution
Weighted	`weight=N`	Servers with different capacity

Health Checks

upstream sockudo_backend {
    server sockudo-1.internal:6001 max_fails=3 fail_timeout=30s;
    server sockudo-2.internal:6001 max_fails=3 fail_timeout=30s;
    
    # Passive health check parameters:
    # max_fails: Mark server as down after 3 failures
    # fail_timeout: Wait 30s before retrying failed server
}

Rate Limiting

Protect Sockudo from abuse with rate limiting:

http {
    # Define rate limit zones
    limit_req_zone $binary_remote_addr zone=websocket:10m rate=5r/s;
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
    limit_req_zone $binary_remote_addr zone=batch_events:10m rate=2r/s;
    
    server {
        # WebSocket connections - 5 per second
        location /app/ {
            limit_req zone=websocket burst=10 nodelay;
            # ...
        }
        
        # Event triggering - 10 per second
        location ~ ^/apps/.*/events$ {
            limit_req zone=api burst=20 nodelay;
            # ...
        }
        
        # Batch events - 2 per second
        location ~ ^/apps/.*/batch_events$ {
            limit_req zone=batch_events burst=5 nodelay;
            # ...
        }
    }
}

Parameters:

zone=name:size - Name and memory size for rate limit state
rate=Xr/s - Allow X requests per second
burst=N - Allow N requests to exceed rate temporarily
nodelay - Don’t delay requests within burst limit

SSL/TLS Best Practices

Modern SSL Configuration

server {
    listen 443 ssl http2;
    
    # Certificate configuration
    ssl_certificate /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;
    
    # Modern SSL protocols only
    ssl_protocols TLSv1.2 TLSv1.3;
    
    # Strong ciphers
    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384';
    ssl_prefer_server_ciphers off;
    
    # Session resumption
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    ssl_session_tickets off;
    
    # OCSP stapling
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_trusted_certificate /etc/nginx/ssl/chain.pem;
    
    # Security headers
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
}

Let’s Encrypt Auto-Renewal

# Test renewal
sudo certbot renew --dry-run

# Automatic renewal (add to crontab)
0 3 * * * certbot renew --quiet --post-hook "systemctl reload nginx"

Monitoring and Logging

Custom Log Format

http {
    log_format sockudo '$remote_addr - $remote_user [$time_local] '
                       '"$request" $status $body_bytes_sent '
                       '"$http_referer" "$http_user_agent" '
                       'upstream: $upstream_addr '
                       'upstream_response_time: $upstream_response_time '
                       'request_time: $request_time '
                       'connection: $connection '
                       'connection_requests: $connection_requests';
    
    access_log /var/log/nginx/sockudo-access.log sockudo;
    error_log /var/log/nginx/sockudo-error.log warn;
}

Metrics Endpoint

# Restrict metrics to internal networks
location /metrics {
    allow 10.0.0.0/8;
    allow 172.16.0.0/12;
    allow 192.168.0.0/16;
    deny all;
    
    proxy_pass http://sockudo_backend:9601;
    proxy_http_version 1.1;
}

Troubleshooting

WebSocket Connection Issues

Problem: WebSocket connections fail with 400 Bad Request. Solution: Ensure WebSocket upgrade headers are configured:

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;

Connection Timeouts

Problem: WebSocket connections drop after 60 seconds. Solution: Increase timeouts:

proxy_read_timeout 300s;  # 5 minutes
proxy_send_timeout 60s;

502 Bad Gateway

Problem: Nginx returns 502 when connecting to Sockudo. Solution:

Verify Sockudo is running: curl http://localhost:6001/up/app-id
Check Nginx error log: sudo tail -f /var/log/nginx/error.log
Verify upstream configuration matches Sockudo’s port
Check firewall rules if Sockudo is on different server

SSL Handshake Failures

Problem: SSL/TLS errors in browser console. Solution:

Verify certificate chain is complete: openssl s_client -connect sockudo.yourdomain.com:443 -showcerts
Check certificate permissions: chmod 644 cert.pem && chmod 600 key.pem
Ensure SSL protocols match client requirements
Test with: curl -v https://sockudo.yourdomain.com/up/app-id

High CPU Usage

Problem: Nginx consuming high CPU with WebSocket connections. Solution:

Enable keepalive connections to upstream:

upstream sockudo_backend {
    server localhost:6001;
    keepalive 64;
}

Increase worker processes: worker_processes auto;
Disable access logging for health checks: access_log off;

Next Steps

Redis Setup - Configure Redis for horizontal scaling
Client Libraries - Configure clients for SSL
Migrating from Pusher - Complete migration guide

Integration Guides

Operations

Using with Nginx

Why Use Nginx with Sockudo?

Basic Configuration

Minimal WebSocket Proxy

Production Configuration

Unix Socket Configuration

Sockudo Configuration

Nginx Configuration

Load Balancing Multiple Nodes

Configuration

Load Balancing Algorithms

Health Checks

Rate Limiting

SSL/TLS Best Practices

Modern SSL Configuration

Let’s Encrypt Auto-Renewal

Monitoring and Logging

Custom Log Format

Metrics Endpoint

Troubleshooting

WebSocket Connection Issues

Connection Timeouts

502 Bad Gateway

SSL Handshake Failures

High CPU Usage

Next Steps

Integration Guides

Operations

Documentation Index

​Why Use Nginx with Sockudo?

​Basic Configuration

​Minimal WebSocket Proxy

​Production Configuration

​Unix Socket Configuration

​Sockudo Configuration

​Nginx Configuration

​Load Balancing Multiple Nodes

​Configuration

​Load Balancing Algorithms

​Health Checks

​Rate Limiting

​SSL/TLS Best Practices

​Modern SSL Configuration

​Let’s Encrypt Auto-Renewal

​Monitoring and Logging

​Custom Log Format

​Metrics Endpoint

​Troubleshooting

​WebSocket Connection Issues

​Connection Timeouts

​502 Bad Gateway

​SSL Handshake Failures

​High CPU Usage

​Next Steps

Why Use Nginx with Sockudo?

Basic Configuration

Minimal WebSocket Proxy

Production Configuration

Unix Socket Configuration

Sockudo Configuration

Nginx Configuration

Load Balancing Multiple Nodes

Configuration

Load Balancing Algorithms

Health Checks

Rate Limiting

SSL/TLS Best Practices

Modern SSL Configuration

Let’s Encrypt Auto-Renewal

Monitoring and Logging

Custom Log Format

Metrics Endpoint

Troubleshooting

WebSocket Connection Issues

Connection Timeouts

502 Bad Gateway

SSL Handshake Failures

High CPU Usage

Next Steps