Reverse proxies

Configure NGINX (and similar proxies) for CrossWatch with correct webhook and WebSocket settings.

Use a reverse proxy for TLS and clean URLs.

Keep CrossWatch on HTTP behind the proxy.

Do not expose CrossWatch directly to the public internet.

Use a VPN for remote access (WireGuard, Tailscale).

Proxy requirements

CrossWatch runs on FastAPI + Uvicorn.

Your proxy must:

• Forward client headers (X-Forwarded-*).

• Support WebSocket upgrades.

• Pass /webhook/* requests through unchanged.

• Use longer timeouts for long-lived connections.

If you add proxy auth, keep /webhook/* reachable.

Trusted reverse proxies (important)

If CrossWatch is behind a reverse proxy, configure Trusted reverse proxies in Settings → Security.

This makes CrossWatch trust the forwarded client headers (X-Forwarded-*).

It improves secure cookie behavior and rate limiting accuracy.

Only trust proxy IPs you control.

Captures and some Tools can take minutes on large libraries.

If your proxy uses default timeouts (often 60–120s), you’ll hit 504 Gateway Timeout.

Set proxy timeouts to at least 10 minutes (600s).

NGINX example

Typical setup:

• Public: https://crosswatch.example.com

• Upstream: http://127.0.0.1:8787

Use a subdomain.

Avoid hosting under a sub-path like /crosswatch/.

nginx.conf (server block)

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

    # TLS config omitted. Use your normal Let's Encrypt / cert config here.

    # Large POSTs are not typical, but this avoids random 413s.
    client_max_body_size 25m;

    # CrossWatch (UI and API)
    location / {
        proxy_pass http://127.0.0.1:8787;

        # Preserve original request details
        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;

        # WebSockets (safe even if the endpoint is plain HTTP)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Captures abd Tools can take minutes.
        # Use 600s (10m) minimum. Raise it if you still see 504s.
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;

        # Don't let NGINX buffer long responses.
        proxy_buffering off;
    }

    # Webhooks should be fast and lossless.
    # If you use proxy auth, exempt this location.
    location ^~ /webhook/ {
        proxy_pass http://127.0.0.1:8787;

        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;

        # Avoid webhook edge-cases with buffering.
        proxy_request_buffering off;
        proxy_buffering off;

        proxy_read_timeout 120s;
        proxy_send_timeout 120s;
    }
}

If CrossWatch runs in Docker

Point proxy_pass to the container on a user-defined Docker network.

Example:

• NGINX container: nginx

• CrossWatch container: crosswatch

• Network: proxy

Use:

• proxy_pass http://crosswatch:8787;

Webhooks and Watcher (important)

CrossWatch exposes inbound webhook endpoints.

See:

• Webhook or Watcher

• Watcher

Webhooks (inbound)

Your proxy must:

• Allow POST to /webhook/*.

• Not rewrite the path.

• Not block unknown content types.

  • Plex can send form-style payloads.

  • Jellyfin/Emby plugins usually send JSON.

If you publish webhook endpoints as https://..., use a publicly trusted certificate.

Self-signed TLS certificates commonly break webhook delivery for Plex, Emby, and Jellyfin.

Use Let’s Encrypt (or similar) at the reverse proxy.

If you put CrossWatch behind login, do one of these:

1. Exempt /webhook/* from auth.

2. IP-allowlist your media server's IP for /webhook/*.

3. Keep webhooks LAN-only. Do not proxy them.

Your media server must reach your public DNS name from inside your LAN.

If it cannot, webhooks will fail.

Fix hairpin NAT. Or use a LAN hostname/IP.

Watcher (outbound)

Watcher mostly makes outbound calls to Plex/Jellyfin/Emby.

Reverse proxying CrossWatch is not required for Watcher itself.

One exception:

• Plex "ratings" helper uses: POST /webhook/plexwatcher?uniqueID

If you enable Plex ratings, your proxy must allow that endpoint. It must also preserve the query string (the ?uniqueID token).

Common proxy problems

413 Request Entity Too Large

Increase client_max_body_size.

502 / 504 / random disconnects

This happens most often when running:

• Captures (create/restore/compare)

• Analyzer / Exporter on large state

Fix: increase timeouts to 10 minutes (600s) or more.

On NGINX, set:

• NGINX: proxy_read_timeout / proxy_send_timeout

If you’re behind an upstream proxy/CDN (Cloudflare, etc.), it may have its own hard timeout.

In that case, bypass the CDN for your CrossWatch hostname.

WebSocket errors (UI features not updating)

Forward upgrade headers:

• proxy_set_header Upgrade $http_upgrade;

• proxy_set_header Connection "upgrade";

Wrong scheme (HTTP/HTTPS) in callbacks or redirects

Send:

• X-Forwarded-Proto $scheme

If you terminate TLS at the proxy, CrossWatch should still behave as HTTPS to clients.

Related topics

• HTTPS/TLS (TLS options and why the proxy approach is recommended)

• Docker setup (ports, volumes, restart policy)