From 5b481765759b3273775b09e1bc54c7f5bc7313dc Mon Sep 17 00:00:00 2001 From: Mauricio Siu Date: Fri, 8 May 2026 22:38:42 -0600 Subject: [PATCH] docs: add Cloudflare Access + trusted origins troubleshooting section Documents the login-hangs-behind-Cloudflare-Access issue and the required configuration (BETTER_AUTH_SECRET, BETTER_AUTH_TRUSTED_ORIGINS, Web Server host/HTTPS settings) to fix it. Closes #4361. --- .../docs/core/guides/cloudflare-tunnels.mdx | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/apps/docs/content/docs/core/guides/cloudflare-tunnels.mdx b/apps/docs/content/docs/core/guides/cloudflare-tunnels.mdx index 05dcc86..3e73a13 100644 --- a/apps/docs/content/docs/core/guides/cloudflare-tunnels.mdx +++ b/apps/docs/content/docs/core/guides/cloudflare-tunnels.mdx @@ -162,4 +162,58 @@ This allows all subdomains (`app1.example.com`, `app2.example.com`, etc.) to rou With wildcard routing, you only need ONE public hostname in Cloudflare Tunnel. Traefik handles routing to different apps based on the domain configured in Dokploy. + + +## Using Cloudflare Access (Zero Trust) with Dokploy + +If you protect your Dokploy dashboard with **Cloudflare Access** (Zero Trust), there are a few extra steps required to make login work correctly. + +### Why login hangs behind Cloudflare Access + +When Cloudflare Access sits in front of Dokploy, the login request (`POST /api/auth/sign-in/email`) may appear to hang indefinitely even with valid credentials. Invalid credentials still return a `401` immediately, which makes it easy to miss this issue. + +The root cause is that Better Auth (Dokploy's auth library) validates the `Origin` header of every request. When the request comes through Cloudflare Access, the origin may not match any of the trusted origins Dokploy knows about, so the request is silently dropped. + +### Required configuration + +You need to configure three things: + +**1. Set a stable `BETTER_AUTH_SECRET`** + +Make sure this value is set and does not change between restarts. If it is missing or rotates, sessions are invalidated and auth flows may break. + +```bash +BETTER_AUTH_SECRET=your-random-secret-here +``` + +Generate a secure value with: + +```bash +openssl rand -hex 32 +``` + +**2. Add your domain to trusted origins** + +Set the `BETTER_AUTH_TRUSTED_ORIGINS` environment variable to include all origins that can reach Dokploy: + +```bash +BETTER_AUTH_TRUSTED_ORIGINS=http://localhost:3000,http://:3000,https://dokploy.example.com +``` + +Replace `dokploy.example.com` with your actual public domain. + +**3. Configure Web Server settings in the Dokploy UI** + +Go to **Settings → Server** and set: +- **Host**: `dokploy.example.com` (your public domain) +- **HTTPS**: enabled + +This ensures Dokploy includes your domain as a trusted origin automatically. + + + After applying these changes, redeploy the Dokploy service so the new environment variables take effect. + + + + If you access Dokploy through multiple origins (public domain, internal IP, Tailscale), make sure all of them are listed in `BETTER_AUTH_TRUSTED_ORIGINS`. \ No newline at end of file