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.
Quick start
Section titled “Quick start”docker run -p 3000:3000 \ -e WORKER_PROXY_TOKEN=$(openssl rand -hex 32) \ ghcr.io/dipjyotimetia/restura:latestAll user data lives in the browser’s IndexedDB — the server is stateless.
docker-compose
Section titled “docker-compose”services: restura: image: ghcr.io/dipjyotimetia/restura:latest ports: - '3000:3000' environment: WORKER_PROXY_TOKEN: ${WORKER_PROXY_TOKEN:?required} ENVIRONMENT: production restart: unless-stoppedThe 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.
Configuration
Section titled “Configuration”| Env var | Purpose | Default |
|---|---|---|
PORT | Listen port | 3000 |
HOST | Bind address | 0.0.0.0 |
WORKER_PROXY_TOKEN | Shared token for X-Restura-Proxy-Token header from the client | required in prod |
REQUIRE_CF_ACCESS | If true (and WORKER_PROXY_TOKEN is unset), accept requests with a verified Cloudflare Access assertion | false |
CF_ACCESS_TEAM_DOMAIN | Access team name, or <team>.cloudflareaccess.com. Required with REQUIRE_CF_ACCESS | |
CF_ACCESS_AUD | Access application audience (AUD) tag. Required with REQUIRE_CF_ACCESS | |
ENVIRONMENT | Anything 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=true | unset (treated as production) |
ALLOW_PRIVATE_IPS | Allow RFC 1918 / link-local upstreams (still blocks cloud-metadata / credential endpoints and loopback) | false |
ALLOWED_ORIGIN | Comma-separated Origin allowlist (supports * wildcards). Under DEV_BYPASS_AUTH it is also the list of cross-origin browsers the bypass admits | unset = no cross-origin access (same-origin only) |
RESTURA_STATIC_ROOT | Path to the SPA bundle | /app/dist/web |
HTTP_PROXY / HTTPS_PROXY / NO_PROXY | Outbound proxy for upstream requests (lowercase variants also work); NO_PROXY hosts bypass it. A per-request upstream proxy set in the app takes precedence | unset = direct |
RATE_LIMITER | Rate-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 them | map |
TRUST_PROXY | If 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 header | false |
DEV_BYPASS_AUTH | Local 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 production | unset |
Auth modes
Section titled “Auth modes”You have two options:
- Shared token — set
WORKER_PROXY_TOKEN; callers send it in theX-Restura-Proxy-Tokenheader (orAuthorization: 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 gets401. Use reverse-proxy auth for browser users. - Cloudflare Access — set
REQUIRE_CF_ACCESS=true,CF_ACCESS_TEAM_DOMAINandCF_ACCESS_AUD, and put Cloudflare Access in front. The server verifies the signedCf-Access-Jwt-Assertionon every request and returns 503 if either variable is missing. Behind any other gateway, set a token and have the gateway addX-Restura-Proxy-Tokenafter it authenticates the user.
Internal network access
Section titled “Internal network access”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.
WebSocket constraints (v1)
Section titled “WebSocket constraints (v1)”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/wsflow, or - A single replica (fine for most internal deployments).
This will be revisited in a future release.
Rate limiting
Section titled “Rate limiting”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.
Related
Section titled “Related”- Reverse proxy — nginx / Caddy / Traefik snippets.
- Security model — the auth gate, SSRF guard.
- Capability matrix — what does not work in self-hosted mode.