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.

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;

    # Main app (UI + 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";

        # Watcher / long polling / slow clients
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;

        # 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

If you enable Plex ratings, your proxy must allow that endpoint.

Common proxy problems

413 Request Entity Too Large

Increase client_max_body_size.

502 / 504 / random disconnects

Increase timeouts:

• NGINX: proxy_read_timeout / proxy_send_timeout

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)