Skip to content

Reverse Proxy Setup

Put Arcane behind Nginx, Apache, or Traefik with WebSockets and the real client IP.

  1. Configure your proxy to forward WebSockets (for live updates) and the real client IP (for login rate limits). Use the examples below.
  2. Set ARCANE_APP_URL to the public URL users open, such as https://arcane.example.com, without the internal :3552 port.
  3. Set ARCANE_TRUSTED_PROXIES so Arcane trusts the client IP the proxy sends.
  4. Make sure the proxy’s header-size limit fits session cookies. See Allow large enough headers.

This example enables WebSockets. Replace the domain name and certificate paths with your own:

server {
listen 80;
server_name arcane.yourdomain.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl http2;
ssl_certificate /etc/letsencrypt/live/arcane.yourdomain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/arcane.yourdomain.com/privkey.pem;
server_name arcane.yourdomain.com;
location / {
add_header X-Robots-Tag "noindex, nofollow";
proxy_pass http://127.0.0.1:3552;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_cache_bypass $http_upgrade;
}
access_log /var/log/nginx/arcane-access.log;
error_log /var/log/nginx/arcane-error.log debug;
}

The proxy_http_version 1.1;, Upgrade, Connection "upgrade", and proxy_cache_bypass lines enable WebSockets. The client IP goes in X-Forwarded-For and X-Real-IP; set ARCANE_TRUSTED_PROXIES so Arcane trusts it.

Trust the proxy with ARCANE_TRUSTED_PROXIES

Section titled “Trust the proxy with ARCANE_TRUSTED_PROXIES”

Without this, login, token refresh, and the OIDC callback rate-limit by the proxy’s IP. That weakens brute-force protection and can lock out every user behind the proxy.

  1. Look up the subnet of the network the proxy and Arcane share:

    Terminal window
    docker network inspect <network> --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}'

    Docker’s default pools use 172.17.0.0–172.31.0.0, then 192.168.0.0/16, but your daemon may differ.

  2. Set it on the Arcane container, for example ARCANE_TRUSTED_PROXIES=172.18.0.0/16. For a single proxy address, use /32, such as ARCANE_TRUSTED_PROXIES=10.0.0.5/32.

  3. Recreate the container.

Arcane then reads the real client IP from X-Forwarded-For for requests from those addresses.

ARCANE_TRUSTED_PROXIES accepts a comma-separated list of CIDR ranges. Write a single address as /32 for IPv4 or /128 for IPv6; Arcane logs a warning and ignores entries without a prefix length. Forwarded headers are trusted only when the direct peer is listed, so untrusted clients can’t spoof X-Forwarded-For. Loopback and private addresses aren’t trusted unless listed. See Environment Variables for all options.

Use this when a TCP (layer 4) proxy or load balancer, such as HAProxy or a Traefik TCP router, passes connections through without adding X-Forwarded-For.

  1. Turn on PROXY protocol (v1 or v2) on the proxy’s connection to Arcane.
  2. Set ARCANE_TRUSTED_PROXIES to the proxy’s range, such as 10.0.0.5/32.
  3. Recreate the container.

Arcane reads the client address from the PROXY header on connections from those addresses. The header is optional there, so HTTP proxies in the same list keep working. Connections from other addresses aren’t parsed for PROXY headers. One invalid entry in ARCANE_TRUSTED_PROXIES turns PROXY protocol off and logs Invalid ARCANE_TRUSTED_PROXIES; PROXY protocol is disabled.

If sign-in fails with oversized-header errors, raise your proxy’s request header limit, such as large_client_header_buffers in Nginx. Current sessions fit in one cookie, but sessions from older releases carry larger ML-DSA-87 (post-quantum) tokens split across up to four cookies until they refresh.

websocket.org has WebSocket guides for other proxies and load balancers: Nginx, Amazon ALB, Cloudflare, and Kubernetes.