Skip to content

Reverse proxy

When you self-host Restura, put it behind your reverse proxy of choice for TLS termination, auth (via Cloudflare Access, OIDC, etc.), and rate limiting.

The container needs the proxy to:

  • Forward /api/ws as a WebSocket upgrade (don’t terminate the upgrade).
  • Pass through the X-Restura-Proxy-Token header or, with Cloudflare Access, the Cf-Access-Jwt-Assertion header.
  • Not strip the Content-Encoding header — streaming responses (SSE, chunked) depend on it.
  • Overwrite True-Client-IP with the real client address, and run the container with TRUST_PROXY=true. The rate limiter keys on the socket peer by default, so without TRUST_PROXY=true every client shares the proxy’s bucket. With it, the server reads CF-Connecting-IP, then True-Client-IP (X-Real-IP and X-Forwarded-For are not used outside development), so the proxy must overwrite True-Client-IP and strip any client-sent CF-Connecting-IP — a value passed through from the client lets the client choose its own bucket.
server {
listen 443 ssl http2;
server_name restura.example.com;
ssl_certificate /etc/ssl/restura.crt;
ssl_certificate_key /etc/ssl/restura.key;
location / {
proxy_pass http://restura:3000;
proxy_http_version 1.1;
proxy_set_header Host $host;
# Overwrites any client-sent value; requires TRUST_PROXY=true on the container
proxy_set_header True-Client-IP $remote_addr;
proxy_set_header CF-Connecting-IP "";
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# WebSocket upgrade
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $http_connection;
# Streaming endpoints
proxy_buffering off;
proxy_read_timeout 1h;
}
}
  1. Put Cloudflare Access in front of restura.example.com and configure your identity provider.
  2. In the Restura container, set REQUIRE_CF_ACCESS=true, CF_ACCESS_TEAM_DOMAIN (your team name) and CF_ACCESS_AUD (the application’s AUD tag), and leave WORKER_PROXY_TOKEN unset.
  3. The server verifies the signed Cf-Access-Jwt-Assertion on every request: signature, issuer, audience and expiry.

See Self-hosting / Docker for the env var names.

WebSocket tickets are per-replica in-memory (v1 constraint). Either use sticky routing on /api/ws-ticket and /api/ws paths, or stick to a single replica.

Per-replica in-memory rate limiting means high-traffic deployments should put a rate limiter in the reverse proxy too. Forwarded client IPs only count when each replica runs with TRUST_PROXY=true behind a proxy that overwrites True-Client-IP.