Reverse Proxy

Put OmniLux behind a reverse proxy for HTTPS, custom domains, and secure remote access.

Caddy (recommended)

Caddy provides automatic HTTPS with Let's Encrypt. This is the simplest setup.

omnilux.example.com {
    reverse_proxy localhost:4000
}

That's it. Caddy handles TLS certificates automatically.

For WebSocket support (game streaming, real-time activity):

omnilux.example.com {
    reverse_proxy localhost:4000 {
        flush_interval -1
    }
}

Nginx

server {
    listen 443 ssl http2;
    server_name omnilux.example.com;

    ssl_certificate     /etc/letsencrypt/live/omnilux.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/omnilux.example.com/privkey.pem;

    client_max_body_size 0;
    proxy_buffering off;

    location / {
        proxy_pass http://127.0.0.1:4000;
        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 support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Streaming — disable buffering and increase timeouts
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

server {
    listen 80;
    server_name omnilux.example.com;
    return 301 https://$server_name$request_uri;
}

Key settings

• client_max_body_size 0 — disables upload size limits (needed for media ingestion)
• proxy_buffering off — prevents Nginx from buffering streaming responses
• proxy_read_timeout 3600s — allows long-lived streaming connections
• WebSocket headers — required for game streaming input relay and activity feed

Traefik

Using Docker labels:

services:
  omnilux:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.omnilux.rule=Host(`omnilux.example.com`)"
      - "traefik.http.routers.omnilux.entrypoints=websecure"
      - "traefik.http.routers.omnilux.tls.certresolver=letsencrypt"
      - "traefik.http.services.omnilux.loadbalancer.server.port=4000"
      # Streaming support
      - "traefik.http.middlewares.omnilux-headers.headers.customrequestheaders.X-Forwarded-Proto=https"
      - "traefik.http.routers.omnilux.middlewares=omnilux-headers"

Add to your Traefik static configuration for WebSocket support:

# traefik.yml
entryPoints:
  websecure:
    address: ":443"
    transport:
      respondingTimeouts:
        readTimeout: 3600s
        writeTimeout: 3600s

Common issues

WebSocket connections failing

Ensure your proxy passes the Upgrade and Connection headers. WebSockets are used for game streaming input relay and the real-time activity feed.

Streaming buffering or stalling

Disable response buffering in your proxy. Nginx uses proxy_buffering off. Caddy does this by default with flush_interval -1.

Large file uploads failing

If you're using media ingestion via upload, ensure your proxy allows large request bodies. Set client_max_body_size 0 in Nginx or remove body size limits in your proxy.

HLS segments not loading

If live TV HLS manifests return 404 for segments, ensure your proxy doesn't cache .m3u8 files. Add Cache-Control: no-cache headers for the /api/livetv/ path.

HDHomeRun discovery not working

HDHomeRun emulation uses SSDP (UDP port 1900). Reverse proxies don't handle UDP. For HDHomeRun discovery to work, clients must be able to reach OmniLux directly on port 1900/udp.