Reverse Proxy

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

Recommended path

For most self-hosted setups:

1. Get the server stable on your LAN first.
2. Put Caddy in front of OmniLux for HTTPS.
3. Add public DNS only after local playback, auth, and scans are working.

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 real-time app activity and live updates

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

Read Remote Access for the recommended browser-access pattern before you open your server to the internet.

WebSocket connections failing

Ensure your proxy passes the Upgrade and Connection headers. WebSockets are used for real-time activity and live updates in the app.

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.