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/wsas a WebSocket upgrade (don’t terminate the upgrade). - Pass through the
X-Restura-Proxy-Tokenheader or, with Cloudflare Access, theCf-Access-Jwt-Assertionheader. - Not strip the
Content-Encodingheader — streaming responses (SSE, chunked) depend on it. - Overwrite
True-Client-IPwith the real client address, and run the container withTRUST_PROXY=true. The rate limiter keys on the socket peer by default, so withoutTRUST_PROXY=trueevery client shares the proxy’s bucket. With it, the server readsCF-Connecting-IP, thenTrue-Client-IP(X-Real-IPandX-Forwarded-Forare not used outside development), so the proxy must overwriteTrue-Client-IPand strip any client-sentCF-Connecting-IP— a value passed through from the client lets the client choose its own bucket.
Example configs
Section titled “Example configs”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; }}restura.example.com { reverse_proxy restura:3000 { transport http { versions h1 h2c keepalive 30s } header_up Host {host} header_up True-Client-IP {remote_host} header_up -CF-Connecting-IP }}Caddy handles WebSocket upgrades and SSE buffering correctly out of the box.
services: restura: image: ghcr.io/dipjyotimetia/restura:latest labels: - traefik.enable=true - traefik.http.routers.restura.rule=Host(`restura.example.com`) - traefik.http.routers.restura.entrypoints=websecure - traefik.http.routers.restura.tls=true - traefik.http.services.restura.loadbalancer.server.port=3000 environment: WORKER_PROXY_TOKEN: ${WORKER_PROXY_TOKEN:?required}With Cloudflare Access
Section titled “With Cloudflare Access”- Put Cloudflare Access in front of
restura.example.comand configure your identity provider. - In the Restura container, set
REQUIRE_CF_ACCESS=true,CF_ACCESS_TEAM_DOMAIN(your team name) andCF_ACCESS_AUD(the application’s AUD tag), and leaveWORKER_PROXY_TOKENunset. - The server verifies the signed
Cf-Access-Jwt-Assertionon every request: signature, issuer, audience and expiry.
See Self-hosting / Docker for the env var names.
Multi-replica notes
Section titled “Multi-replica notes”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.
Related
Section titled “Related”- Docker — env vars and the single-image setup.
- Security model.