Reverse Proxy Configuration for COBY

Since COBY now serves both the API and web dashboard from port 8080, here are configuration examples for common reverse proxies.

Nginx Reverse Proxy

# COBY upstream
upstream coby_backend {
    server coby-app:8080;
    # Add more servers for load balancing if needed
    # server coby-app-2:8080;
}

server {
    listen 80;
    server_name coby.yourdomain.com;
    
    # Optional: Redirect HTTP to HTTPS
    # return 301 https://$server_name$request_uri;
    
    # Main application proxy
    location / {
        proxy_pass http://coby_backend;
        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;
        proxy_read_timeout 86400;
        
        # CORS headers (if needed)
        add_header Access-Control-Allow-Origin *;
        add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";
        add_header Access-Control-Allow-Headers "DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range";
    }
    
    # WebSocket specific configuration (if needed separately)
    location /ws/ {
        proxy_pass http://coby_backend;
        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_read_timeout 86400;
    }
    
    # Health check endpoint
    location /health {
        proxy_pass http://coby_backend;
        access_log off;
    }
    
    # Optional: Serve static files with caching
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        proxy_pass http://coby_backend;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

# HTTPS configuration (recommended)
server {
    listen 443 ssl http2;
    server_name coby.yourdomain.com;
    
    # SSL configuration
    ssl_certificate /path/to/your/certificate.crt;
    ssl_certificate_key /path/to/your/private.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;
    
    # Same location blocks as above
    location / {
        proxy_pass http://coby_backend;
        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;
        proxy_read_timeout 86400;
    }
}

Apache Reverse Proxy

<VirtualHost *:80>
    ServerName coby.yourdomain.com
    
    # Enable required modules
    # a2enmod proxy proxy_http proxy_wstunnel rewrite
    
    # Proxy configuration
    ProxyPreserveHost On
    ProxyRequests Off
    
    # Main application
    ProxyPass / http://coby-app:8080/
    ProxyPassReverse / http://coby-app:8080/
    
    # WebSocket support
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule ^/?(.*) "ws://coby-app:8080/$1" [P,L]
    
    # Headers
    ProxyPassReverse / http://coby-app:8080/
    ProxyPassReverseMatch ^(/.*) http://coby-app:8080$1
    
    # Optional: Logging
    ErrorLog ${APACHE_LOG_DIR}/coby_error.log
    CustomLog ${APACHE_LOG_DIR}/coby_access.log combined
</VirtualHost>

# HTTPS version
<VirtualHost *:443>
    ServerName coby.yourdomain.com
    
    # SSL configuration
    SSLEngine on
    SSLCertificateFile /path/to/your/certificate.crt
    SSLCertificateKeyFile /path/to/your/private.key
    
    # Same proxy configuration as above
    ProxyPreserveHost On
    ProxyRequests Off
    ProxyPass / http://coby-app:8080/
    ProxyPassReverse / http://coby-app:8080/
    
    # WebSocket support
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule ^/?(.*) "ws://coby-app:8080/$1" [P,L]
</VirtualHost>

Traefik (Docker Labels)

If you're using Traefik, add these labels to your COBY app service in docker-compose:

coby-app:
  # ... other configuration
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.coby.rule=Host(`coby.yourdomain.com`)"
    - "traefik.http.routers.coby.entrypoints=websecure"
    - "traefik.http.routers.coby.tls.certresolver=letsencrypt"
    - "traefik.http.services.coby.loadbalancer.server.port=8080"
    
    # WebSocket support
    - "traefik.http.routers.coby-ws.rule=Host(`coby.yourdomain.com`) && PathPrefix(`/ws`)"
    - "traefik.http.routers.coby-ws.entrypoints=websecure"
    - "traefik.http.routers.coby-ws.tls.certresolver=letsencrypt"
    - "traefik.http.services.coby-ws.loadbalancer.server.port=8081"

Caddy

coby.yourdomain.com {
    reverse_proxy coby-app:8080
    
    # WebSocket support is automatic in Caddy
    
    # Optional: Custom headers
    header {
        # Security headers
        X-Frame-Options "SAMEORIGIN"
        X-XSS-Protection "1; mode=block"
        X-Content-Type-Options "nosniff"
        Referrer-Policy "no-referrer-when-downgrade"
    }
    
    # Optional: Logging
    log {
        output file /var/log/caddy/coby.log
    }
}

HAProxy

global
    daemon
    
defaults
    mode http
    timeout connect 5000ms
    timeout client 50000ms
    timeout server 50000ms
    
frontend coby_frontend
    bind *:80
    bind *:443 ssl crt /path/to/your/certificate.pem
    redirect scheme https if !{ ssl_fc }
    
    # WebSocket detection
    acl is_websocket hdr(Upgrade) -i websocket
    acl is_websocket_path path_beg /ws
    
    use_backend coby_websocket if is_websocket or is_websocket_path
    default_backend coby_backend
    
backend coby_backend
    balance roundrobin
    option httpchk GET /health
    server coby1 coby-app:8080 check
    
backend coby_websocket
    balance roundrobin
    server coby1 coby-app:8081 check

Docker Compose with Reverse Proxy

Here's an example of how to integrate with an existing reverse proxy network:

# Add to your docker-compose.portainer.yml
networks:
  coby-network:
    driver: bridge
  reverse-proxy:
    external: true  # Your existing reverse proxy network

services:
  coby-app:
    # ... existing configuration
    networks:
      - coby-network
      - reverse-proxy  # Connect to reverse proxy network
    # Remove port mappings if using reverse proxy
    # ports:
    #   - "8080:8080"
    #   - "8081:8081"

Important Notes

WebSocket Support: Ensure your reverse proxy supports WebSocket upgrades for real-time features
Health Checks: Configure health checks to use /health endpoint
Timeouts: Set appropriate timeouts for long-running WebSocket connections
SSL/TLS: Always use HTTPS in production
Rate Limiting: Consider implementing rate limiting at the reverse proxy level
Caching: Static assets can be cached at the reverse proxy level
Load Balancing: If scaling horizontally, configure load balancing appropriately

Testing Your Configuration

After configuring your reverse proxy:

Basic connectivity: curl http://your-domain/health
Web dashboard: Visit http://your-domain/ in browser
API endpoints: Test http://your-domain/api/ endpoints
WebSocket: Test WebSocket connections to /ws/ path
SSL: Verify HTTPS is working if configured

The COBY application will handle all routing internally, so your reverse proxy just needs to forward all traffic to port 8080.

8.0 KiB Raw Blame History