Skip to content

Self-hosting with Docker

The self-hosted Restura is a single Node container that serves the SPA and the /api/* proxy on one port. Same Hono app that runs in the Cloudflare Worker — just with Node adapters for CONNECT proxying and native WebSockets.

Terminal window
docker run -p 3000:3000 \
-e WORKER_PROXY_TOKEN=$(openssl rand -hex 32) \
ghcr.io/dipjyotimetia/restura:latest

All user data lives in the browser’s IndexedDB — the server is stateless.

services:
restura:
image: ghcr.io/dipjyotimetia/restura:latest
ports:
- '3000:3000'
environment:
WORKER_PROXY_TOKEN: ${WORKER_PROXY_TOKEN:?required}
ENVIRONMENT: production
restart: unless-stopped

The repo ships a docker-compose.yml you can copy. It publishes the port on all interfaces, so it needs WORKER_PROXY_TOKEN or Cloudflare Access.

docker-compose.local.yml is a source-build smoke stack that runs with DEV_BYPASS_AUTH=true (unauthenticated). It publishes on 127.0.0.1 only (127.0.0.1:${RESTURA_LOCAL_PORT:-3000}) — don’t widen that binding.

Every POST /api/* must carry Content-Type: application/json; other content types get 415, in every auth mode.

Env varPurposeDefault
PORTListen port3000
HOSTBind address0.0.0.0
WORKER_PROXY_TOKENShared token for X-Restura-Proxy-Token header from the clientrequired in prod
REQUIRE_CF_ACCESSIf true (and WORKER_PROXY_TOKEN is unset), accept requests with a verified Cloudflare Access assertionfalse
CF_ACCESS_TEAM_DOMAINAccess team name, or <team>.cloudflareaccess.com. Required with REQUIRE_CF_ACCESS
CF_ACCESS_AUDAccess application audience (AUD) tag. Required with REQUIRE_CF_ACCESS
ENVIRONMENTAnything other than development enforces the full SSRF guard. development alone does not allow localhost upstreams on Node: loopback targets (requests, upstream proxy, WebSocket) also need DEV_BYPASS_AUTH=trueunset (treated as production)
ALLOW_PRIVATE_IPSAllow RFC 1918 / link-local upstreams (still blocks cloud-metadata / credential endpoints and loopback)false
ALLOWED_ORIGINComma-separated Origin allowlist (supports * wildcards). Under DEV_BYPASS_AUTH it is also the list of cross-origin browsers the bypass admitsunset = no cross-origin access (same-origin only)
RESTURA_STATIC_ROOTPath to the SPA bundle/app/dist/web
HTTP_PROXY / HTTPS_PROXY / NO_PROXYOutbound proxy for upstream requests (lowercase variants also work); NO_PROXY hosts bypass it. A per-request upstream proxy set in the app takes precedenceunset = direct
RATE_LIMITERRate-limiter backend. Use map (the Node default) or omit it. binding and binding-shadow need Cloudflare’s Rate Limiting binding, so the Node server exits at startup if you set themmap
TRUST_PROXYIf true, rate limiting keys on the client-IP header (CF-Connecting-IP / True-Client-IP) instead of the socket peer. Set only behind a reverse proxy that overwrites that headerfalse
DEV_BYPASS_AUTHLocal development only — skips auth when ENVIRONMENT=development. Requests addressed to any host other than localhost / 127.0.0.1 / [::1] (DNS-rebinding defence), and browser requests from a foreign Origin (not same-origin, not in ALLOWED_ORIGIN), are still refused with 403. Never set this in productionunset

You have two options:

  1. Shared token — set WORKER_PROXY_TOKEN; callers send it in the X-Restura-Proxy-Token header (or Authorization: Bearer). The SPA only sends a token baked in at build time (VITE_WORKER_PROXY_TOKEN), and the stock image has none — so this mode protects scripted access, but the bundled web UI gets 401. Use reverse-proxy auth for browser users.
  2. Cloudflare Access — set REQUIRE_CF_ACCESS=true, CF_ACCESS_TEAM_DOMAIN and CF_ACCESS_AUD, and put Cloudflare Access in front. The server verifies the signed Cf-Access-Jwt-Assertion on every request and returns 503 if either variable is missing. Behind any other gateway, set a token and have the gateway add X-Restura-Proxy-Token after it authenticates the user.

By default the SSRF guard blocks any RFC 1918 / link-local upstream — even from your self-hosted instance. If you genuinely want to proxy to internal services, set ALLOW_PRIVATE_IPS=true. Cloud metadata and credential endpoints (169.254.169.254, ECS 169.254.170.2, 169.254.169.253, 169.254.169.123, Alibaba 100.100.100.200, AWS/GCE IPv6 metadata) stay blocked regardless, as does loopback outside local development — both for literal addresses and for DNS names that resolve to them. Each upstream connection is pinned to the address the guard validated, so DNS rebinding cannot swap in an internal address after the check.

The WebSocket ticket store is per-replica in-memory. Tickets expire in 30 seconds. If you run multiple replicas behind a load balancer, you need either:

  • Sticky session routing for the /api/ws-ticket → /api/ws flow, or
  • A single replica (fine for most internal deployments).

This will be revisited in a future release.

Per-replica in-memory token bucket, keyed by client IP plus the authenticated principal. The client IP is the socket peer unless TRUST_PROXY=true, so behind a reverse proxy set TRUST_PROXY=true and have the proxy overwrite True-Client-IP (and strip any client-sent CF-Connecting-IP, which is read first) — otherwise every client shares the proxy’s bucket. For multi-replica deployments, put a rate limiter (Cloudflare, nginx, Envoy) in front.