Fix Reverse Proxy Support

.github/copilot-instructions.md

@@ -186,6 +186,7 @@ Pluggable providers in `cps/metadata_provider/`:
 - `CWA_WATCH_MODE`: Force polling watcher (`poll`) or inotify (default)
 - `HARDCOVER_TOKEN`: API key for Hardcover metadata provider
 - `COOKIE_PREFIX`: Custom prefix for session cookies
+- `TRUSTED_PROXY_COUNT`: Number of proxies to trust for X-Forwarded-* headers (default: 1, use 2+ for CF Tunnel + reverse proxy)
 
 ## Common Pitfalls
 1. **Don't import SQLite on main thread**: Always use `init_db_thread()` in background tasks
@@ -195,6 +196,7 @@ Pluggable providers in `cps/metadata_provider/`:
 5. **WAL mode errors**: Usually means network share deployment without `NETWORK_SHARE_MODE=true`
 6. **Port binding**: Ports below 1024 need `cap_add: [NET_BIND_SERVICE]` in docker-compose
 7. **Calibre plugins**: Requires `customize.py.json` in `/config/.config/calibre/` to register
+8. **Session protection errors**: Behind multiple proxies? Set `TRUSTED_PROXY_COUNT` to match your proxy chain depth
 
 ## Version Management
 - **Installed version**: `/app/CWA_RELEASE` (baked at build time)

README.md

@@ -100,6 +100,16 @@ This tells CWA to avoid enabling WAL on the Calibre `metadata.db` and the `app.d
 - On Docker Desktop (Windows/macOS), the container runs on a LinuxKit/WSL2 VM and host-mounted paths may not propagate `inotify` events reliably. CWA auto-detects Docker Desktop at startup and prefers the same polling watcher for reliability.
 - Advanced: You can also force polling regardless of share mode by setting `CWA_WATCH_MODE=poll`.
 
+### Running behind multiple proxies (Cloudflare Tunnel, reverse proxy)
+
+- CWA uses Werkzeug's ProxyFix middleware to properly handle `X-Forwarded-For`, `X-Forwarded-Proto`, and other proxy headers.
+- By default, it trusts **1 proxy** in the chain. If you have multiple proxies (e.g., Cloudflare Tunnel → nginx → CWA), set:
+
+  - `TRUSTED_PROXY_COUNT=2` (or the total number of proxies in your chain)
+
+- **Why this matters**: Session protection validates requests based on the client's IP address. If ProxyFix doesn't trust enough proxies, it may see different IPs between requests, causing "Session protection triggered" warnings and forcing re-login.
+- **Troubleshooting**: If you see frequent session protection warnings in logs, check your proxy chain depth and adjust this variable accordingly.
+
 ## **_Features:_**
 
 ### CWA supports all Stock CW Features:

cps/__init__.py

@@ -83,7 +83,11 @@ app.config.update(
 
 # Fix for running behind reverse proxy (e.g. nginx, apache, caddy, ...)
 # Without it, url_for will generate http:// urls even if https:// is used
-app.wsgi_app = ProxyFix(app.wsgi_app, x_for=1, x_proto=1)
+# Set TRUSTED_PROXY_COUNT to the number of proxies in your chain (default: 1)
+# For CF Tunnel + reverse proxy, use TRUSTED_PROXY_COUNT=2
+num_proxies = int(os.environ.get('TRUSTED_PROXY_COUNT', '1'))
+app.wsgi_app = ProxyFix(app.wsgi_app, x_for=num_proxies, x_proto=num_proxies, x_host=num_proxies, x_prefix=num_proxies)
+log.info(f'ProxyFix configured to trust {num_proxies} proxy(ies) for X-Forwarded-* headers')
 
 lm = MyLoginManager()
 

docker-compose.yml

@@ -19,6 +19,9 @@ services:
       - NETWORK_SHARE_MODE=false
       # If you want to force polling mode regardless of share type, set CWA_WATCH_MODE=poll
       # - CWA_WATCH_MODE=poll
+      # If running behind multiple proxies (e.g., Cloudflare Tunnel + reverse proxy), set the total number of proxies
+      # This ensures proper IP detection for session protection and rate limiting (default: 1)
+      # - TRUSTED_PROXY_COUNT=2
       # Skip the automatic library detection/mount at startup. When enabled, the auto-library service will not run.
       # Accepts: true/yes/1 to disable auto-mount (default: false)
       # - DISABLE_LIBRARY_AUTOMOUNT=false