SSL/TLS Configuration

Sockudo supports SSL/TLS for secure WebSocket connections (WSS) and HTTPS API endpoints. This guide covers certificate configuration, HTTP to HTTPS redirection, and production deployment.

Basic SSL Configuration

Enable SSL in your configuration file:

{
  "ssl": {
    "enabled": true,
    "cert_path": "/app/ssl/cert.pem",
    "key_path": "/app/ssl/key.pem"
  }
}

Or via environment variables:

SSL_ENABLED=true
SSL_CERT_PATH=/app/ssl/cert.pem
SSL_KEY_PATH=/app/ssl/key.pem

ssl.enabled

boolean

default:"false"

Enable SSL/TLS for HTTPS and secure WebSocket (WSS) connections.

ssl.cert_path

string

required

Path to SSL certificate file (PEM format).

ssl.key_path

string

required

Path to SSL private key file (PEM format).

Certificate Formats

Sockudo accepts SSL certificates in PEM format. Most certificate authorities provide certificates in this format.

Certificate File Structure

Your certificate file should contain:

Your domain certificate
Intermediate certificates (if any)
Root CA certificate (optional)

Private Key File

Your private key should be in unencrypted PEM format:

-----BEGIN PRIVATE KEY-----
[Your private key]
-----END PRIVATE KEY-----

Or RSA format:

-----BEGIN RSA PRIVATE KEY-----
[Your private key]
-----END RSA PRIVATE KEY-----

Self-Signed Certificates (Development)

For development and testing, you can generate self-signed certificates:

# Generate self-signed certificate (valid for 365 days)
openssl req -x509 -newkey rsa:4096 -nodes \
  -keyout key.pem \
  -out cert.pem \
  -days 365 \
  -subj "/CN=localhost"

# For multiple domains/IPs
openssl req -x509 -newkey rsa:4096 -nodes \
  -keyout key.pem \
  -out cert.pem \
  -days 365 \
  -subj "/CN=localhost" \
  -addext "subjectAltName=DNS:localhost,DNS:*.localhost,IP:127.0.0.1"

Self-signed certificates will trigger browser warnings. They should never be used in production.

Let’s Encrypt (Production)

For production deployments, use Let’s Encrypt for free, automated SSL certificates.

Using Certbot

# Install certbot
sudo apt-get update
sudo apt-get install certbot

# Generate certificate
sudo certbot certonly --standalone \
  -d your-domain.com \
  -d www.your-domain.com \
  --email your-email@example.com \
  --agree-tos

# Certificates will be stored in:
# /etc/letsencrypt/live/your-domain.com/fullchain.pem (cert)
# /etc/letsencrypt/live/your-domain.com/privkey.pem (key)

Sockudo Configuration

SSL_ENABLED=true
SSL_CERT_PATH=/etc/letsencrypt/live/your-domain.com/fullchain.pem
SSL_KEY_PATH=/etc/letsencrypt/live/your-domain.com/privkey.pem

Auto-Renewal

Let’s Encrypt certificates expire after 90 days. Set up auto-renewal:

# Test renewal
sudo certbot renew --dry-run

# Add to crontab for auto-renewal (runs twice daily)
sudo crontab -e

# Add this line:
0 0,12 * * * certbot renew --quiet --post-hook "systemctl reload sockudo"

HTTP to HTTPS Redirect

When SSL is enabled, you can automatically redirect HTTP traffic to HTTPS:

{
  "ssl": {
    "enabled": true,
    "cert_path": "/app/ssl/cert.pem",
    "key_path": "/app/ssl/key.pem",
    "redirect_http": true,
    "http_port": 80
  }
}

SSL_ENABLED=true
SSL_REDIRECT_HTTP=true
SSL_HTTP_PORT=80

ssl.redirect_http

boolean

default:"false"

Enable HTTP to HTTPS redirection. Starts an HTTP server that redirects all requests to HTTPS.

ssl.http_port

number

default:"80"

HTTP port to listen on for redirects (typically 80).

When redirect_http is enabled, Sockudo starts two servers:

HTTPS server on the configured port (default: 6001)
HTTP server on http_port (default: 80) that redirects to HTTPS

Domain Configuration

# Set domain name for certificate validation and redirects
DOMAIN=your-domain.com

DOMAIN

string

default:"localhost"

Domain name used for SSL certificate validation and redirect URLs.

Client Connection

Once SSL is enabled, clients must connect using secure protocols:

JavaScript (Pusher-compatible)

const pusher = new Pusher('app-key', {
  wsHost: 'your-domain.com',
  wsPort: 6001,
  forceTLS: true,  // Use WSS (secure WebSocket)
  encrypted: true,
  enabledTransports: ['ws', 'wss']
});

Direct WebSocket

// Secure WebSocket connection
const ws = new WebSocket('wss://your-domain.com:6001/app/app-key');

REST API

# HTTPS API endpoint
curl -X POST https://your-domain.com:6001/apps/app-id/events \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-event",
    "channel": "my-channel",
    "data": "{\"message\":\"Hello\"}"
  }'

Reverse Proxy Setup

For production, it’s common to run Sockudo behind a reverse proxy (Nginx, HAProxy, Caddy) that handles SSL termination.

Nginx SSL Termination

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    # SSL security settings
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # Proxy to Sockudo (without SSL)
    location / {
        proxy_pass http://localhost:6001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header 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;
        proxy_cache_bypass $http_upgrade;
    }
}

# HTTP to HTTPS redirect
server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

Sockudo Configuration (Behind Proxy)

When using SSL termination at the proxy level, disable SSL in Sockudo:

# Sockudo listens on HTTP (proxy handles SSL)
SSL_ENABLED=false
HOST=127.0.0.1  # Only accept local connections
PORT=6001

Nginx with Unix Socket

For better performance, use Unix sockets:

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

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location / {
        proxy_pass http://sockudo;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

# Sockudo configuration
UNIX_SOCKET_ENABLED=true
UNIX_SOCKET_PATH=/var/run/sockudo/sockudo.sock

SSL Best Practices

Security

Use strong certificate key sizes (2048-bit minimum, 4096-bit recommended)
Enable TLS 1.2 and TLS 1.3 only (disable older protocols)
Use strong cipher suites
Keep certificates up to date (monitor expiration)
Protect private key files (permissions: 600)
Never commit certificates or keys to version control

Performance

Enable SSL session caching to reduce handshake overhead
Consider SSL termination at proxy/load balancer level
Use HTTP/2 when possible (better performance over SSL)

Monitoring

Monitor certificate expiration dates
Set up alerts for certificates expiring in < 30 days
Log SSL handshake failures
Monitor SSL connection errors

Troubleshooting

Certificate Validation Errors

# Verify certificate and key match
openssl x509 -noout -modulus -in cert.pem | openssl md5
openssl rsa -noout -modulus -in key.pem | openssl md5
# The MD5 hashes should match

# Check certificate details
openssl x509 -in cert.pem -text -noout

# Verify certificate chain
openssl verify -CAfile ca-bundle.pem cert.pem

Connection Issues

# Test SSL connection
openssl s_client -connect your-domain.com:6001 -servername your-domain.com

# Test WebSocket over SSL
wscat -c wss://your-domain.com:6001/app/app-key

Permission Issues

# Ensure Sockudo can read certificate files
sudo chown sockudo:sockudo /etc/letsencrypt/live/your-domain.com/*.pem
sudo chmod 600 /etc/letsencrypt/live/your-domain.com/privkey.pem
sudo chmod 644 /etc/letsencrypt/live/your-domain.com/fullchain.pem

Port Binding

If you get “permission denied” when binding to port 443:

# Option 1: Run as root (not recommended)
sudo ./sockudo

# Option 2: Grant capability to bind privileged ports
sudo setcap 'cap_net_bind_service=+ep' /path/to/sockudo

# Option 3: Use reverse proxy (recommended)
# Nginx/Caddy runs on 443, proxies to Sockudo on 6001

Getting Started

Core Concepts

Configuration

Deployment

Advanced Features

SSL/TLS Configuration

Basic SSL Configuration

Certificate Formats

Certificate File Structure

Private Key File

Self-Signed Certificates (Development)

Let’s Encrypt (Production)

Using Certbot

Sockudo Configuration

Auto-Renewal

HTTP to HTTPS Redirect

Domain Configuration

Client Connection

JavaScript (Pusher-compatible)

Direct WebSocket

REST API

Reverse Proxy Setup

Nginx SSL Termination

Sockudo Configuration (Behind Proxy)

Nginx with Unix Socket

SSL Best Practices

Security

Performance

Monitoring

Troubleshooting

Certificate Validation Errors

Connection Issues

Permission Issues

Port Binding

Next Steps

WebSocket Configuration

Production Deployment

Getting Started

Core Concepts

Configuration

Deployment

Advanced Features

Documentation Index

​Basic SSL Configuration

​Certificate Formats

​Certificate File Structure

​Private Key File

​Self-Signed Certificates (Development)

​Let’s Encrypt (Production)

​Using Certbot

​Sockudo Configuration

​Auto-Renewal

​HTTP to HTTPS Redirect

​Domain Configuration

​Client Connection

​JavaScript (Pusher-compatible)

​Direct WebSocket

​REST API

​Reverse Proxy Setup

​Nginx SSL Termination

​Sockudo Configuration (Behind Proxy)

​Nginx with Unix Socket

​SSL Best Practices

​Security

​Performance

​Monitoring

​Troubleshooting

​Certificate Validation Errors

​Connection Issues

​Permission Issues

​Port Binding

​Next Steps

WebSocket Configuration

Production Deployment

Basic SSL Configuration

Certificate Formats

Certificate File Structure

Private Key File

Self-Signed Certificates (Development)

Let’s Encrypt (Production)

Using Certbot

Sockudo Configuration

Auto-Renewal

HTTP to HTTPS Redirect

Domain Configuration

Client Connection

JavaScript (Pusher-compatible)

Direct WebSocket

REST API

Reverse Proxy Setup

Nginx SSL Termination

Sockudo Configuration (Behind Proxy)

Nginx with Unix Socket

SSL Best Practices

Security

Performance

Monitoring

Troubleshooting

Certificate Validation Errors

Connection Issues

Permission Issues

Port Binding

Next Steps