Reverse Proxy Setup
Put Arcane behind Nginx, Apache, or Traefik with WebSockets and the real client IP.
- Configure your proxy to forward WebSockets (for live updates) and the real client IP (for login rate limits). Use the examples below.
- Set
ARCANE_APP_URLto the public URL users open, such ashttps://arcane.example.com, without the internal:3552port. - Set
ARCANE_TRUSTED_PROXIESso Arcane trusts the client IP the proxy sends. - Make sure the proxy’s header-size limit fits session cookies. See Allow large enough headers.
Configure your proxy
Section titled “Configure your proxy”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.
On Apache 2.4.47 or later, use mod_proxy_http and a ProxyPassMatch rule with upgrade=websocket:
Define HOST arcane.example.comDefine PORT 3552
<VirtualHost *:443> ServerName ${HOST}
ProxyPassMatch ^/(.*)\/ws\/(.*)$ ws://127.0.0.1:${PORT}/$1/ws/$2 upgrade=websocket ProxyPass / http://127.0.0.1:${PORT}/ ProxyPassReverse / http://127.0.0.1:${PORT}/
ErrorLog ${APACHE_LOG_DIR}/arcane.error.log CustomLog ${APACHE_LOG_DIR}/arcane.access.log combined
Include /etc/letsencrypt/options-ssl-apache.conf SSLCertificateFile /etc/letsencrypt/live/${HOST}/fullchain.pem SSLCertificateKeyFile /etc/letsencrypt/live/${HOST}/privkey.pem</VirtualHost>mod_proxy adds X-Forwarded-For automatically; set ARCANE_TRUSTED_PROXIES so Arcane trusts it.
Traefik forwards WebSockets without extra middleware. Agents on auto or grpc transport also open a gRPC tunnel to /api/tunnel/connect, which Traefik must forward as h2c without a timeout. Without agents, you only need the web router in step 2.
1. Turn off the HTTPS read timeout
Section titled “1. Turn off the HTTPS read timeout”Traefik’s HTTPS entrypoint times out after 60 seconds by default, killing the gRPC stream. Add this to the Traefik command (or static config). It goes on the entrypoint, not a router. See Traefik’s responding timeouts.
command: - "--entrypoints.websecure.transport.respondingtimeouts.readtimeout=0s"2. Add gRPC and web routers
Section titled “2. Add gRPC and web routers”Put these labels on your Arcane service. Change arcane.example.com, letsencrypt, and proxy to your hostname, certificate resolver, and Traefik’s Docker network. ARCANE_TRUSTED_PROXIES is that network’s subnet (how to look it up).
services: arcane: image: ghcr.io/getarcaneapp/manager:latest environment: - ARCANE_APP_URL=https://arcane.example.com - ARCANE_TRUSTED_PROXIES=172.18.0.0/16 networks: - proxy labels: - traefik.enable=true - traefik.docker.network=proxy - "traefik.http.routers.arcane-grpc.rule=Host(`arcane.example.com`) && Path(`/api/tunnel/connect`) && Method(`POST`) && HeaderRegexp(`Content-Type`, `^application/grpc`)" - traefik.http.routers.arcane-grpc.entrypoints=websecure - traefik.http.routers.arcane-grpc.priority=100 - traefik.http.routers.arcane-grpc.tls.certresolver=letsencrypt - traefik.http.routers.arcane-grpc.service=arcane-grpc - traefik.http.services.arcane-grpc.loadbalancer.server.port=3552 - traefik.http.services.arcane-grpc.loadbalancer.server.scheme=h2c - "traefik.http.routers.arcane-web.rule=Host(`arcane.example.com`)" - traefik.http.routers.arcane-web.entrypoints=websecure - traefik.http.routers.arcane-web.priority=10 - traefik.http.routers.arcane-web.tls.certresolver=letsencrypt - traefik.http.routers.arcane-web.service=arcane-web - traefik.http.services.arcane-web.loadbalancer.server.port=3552 - traefik.http.services.arcane-web.loadbalancer.server.scheme=http
networks: proxy: external: trueThe gRPC router takes POST /api/tunnel/connect; everything else, including WebSockets, uses the web router. See Traefik’s exposing gRPC for more on h2c backends.
3. Point the agent at that URL
Section titled “3. Point the agent at that URL”ARCANE_MANAGER_API_URL should match ARCANE_APP_URL. See Remote Agents if you haven’t created the agent yet.
environment: - ARCANE_AGENT=true - ARCANE_AGENT_TRANSPORT=auto - ARCANE_MANAGER_API_URL=https://arcane.example.com - ARCANE_AGENT_TOKEN=arc_etkn_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX4. Restart and check the agent logs
Section titled “4. Restart and check the agent logs”- Success:
Agent tunnel connected to managerwithtransport=grpc. - No gRPC forwarding:
gRPC agent tunnel connection failed, falling back to websocket transport.
docker restart traefik arcane-agentdocker logs -f arcane-agentTrust 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.
-
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, then192.168.0.0/16, but your daemon may differ. -
Set it on the Arcane container, for example
ARCANE_TRUSTED_PROXIES=172.18.0.0/16. For a single proxy address, use/32, such asARCANE_TRUSTED_PROXIES=10.0.0.5/32. -
Recreate the container.
Arcane then reads the real client IP from X-Forwarded-For for requests from those addresses.
Details
Section titled “Details”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.
PROXY protocol
Section titled “PROXY protocol”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.
- Turn on PROXY protocol (v1 or v2) on the proxy’s connection to Arcane.
- Set
ARCANE_TRUSTED_PROXIESto the proxy’s range, such as10.0.0.5/32. - 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.
Allow large enough headers
Section titled “Allow large enough headers”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.
Other proxies
Section titled “Other proxies”websocket.org has WebSocket guides for other proxies and load balancers: Nginx, Amazon ALB, Cloudflare, and Kubernetes.