~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
docs(deployment): add reverse-proxy deployment guide (#4837)
LearningCircuitd85d6c8d2225
diff --git a/docs/decisions/0005-reject-inapp-response-compression.md b/docs/decisions/0005-reject-inapp-response-compression.mdindex 705dc236a6..5acae7e251 100644--- a/docs/decisions/0005-reject-inapp-response-compression.md+++ b/docs/decisions/0005-reject-inapp-response-compression.md@@ -63,7 +63,8 @@ trade for a local-first tool.re-introduce `flask-compress` or an equivalent runtime compressor.For remote / multi-user deployments, the guidance is to **front LDR with a-reverse proxy** (nginx / Caddy), which handles TLS, compression, and caching.+reverse proxy** (nginx / Caddy), which handles TLS, compression, and caching —+see [Deploying behind a reverse proxy](../deployment/reverse-proxy.md).If asset compression is ever genuinely wanted *without* a proxy, use**build-time pre-compression** instead: have Vite emit `.br` / `.gz` artifactsdiff --git a/docs/deployment/reverse-proxy.md b/docs/deployment/reverse-proxy.mdnew file mode 100644index 0000000000..f41447cc1a--- /dev/null+++ b/docs/deployment/reverse-proxy.md@@ -0,0 +1,182 @@+# Deploying behind a reverse proxy++For anything beyond a single user on `localhost`, run LDR behind a reverse proxy+(nginx, Caddy, Traefik, Nginx Proxy Manager, …). The proxy terminates TLS and+handles **HTTPS, response compression, and static-asset caching** for you — so+LDR itself does none of those (see+[ADR-0005](../decisions/0005-reject-inapp-response-compression.md) on why+compression is intentionally the proxy's job, not the app's).++> **Bind LDR to loopback and expose only the proxy.** LDR's default+> `LDR_WEB_HOST` is `0.0.0.0` (all interfaces) and it always serves **plain+> HTTP**. Set `LDR_WEB_HOST=127.0.0.1` (or, for Docker, publish to loopback:+> `-p 127.0.0.1:5000:5000`, or use an internal network). This matters for+> security — see the next section.++The config below is **illustrative**; directive syntax evolves, so follow the+linked upstream docs for the current spelling. `5000` is LDR's default port+(`LDR_WEB_PORT`); substitute yours if you changed it.++## What LDR expects from the proxy++LDR uses Werkzeug's+[`ProxyFix`](https://werkzeug.palletsprojects.com/en/stable/middleware/proxy_fix/)+with `x_for=1, x_proto=1` (and `x_host=0, x_port=0`). This makes it read the+**right-most value** of each forwarded header — the one appended by the single+proxy directly in front of LDR. `ProxyFix` does not count or validate hops; the+count just has to equal the number of trusted proxies.++| Forwarded header | Used by LDR? | For |+|---|---|---|+| `X-Forwarded-For` | yes | client IP — rate limiting, logging |+| `X-Forwarded-Proto` | yes | http/https detection → secure cookies, HSTS, the WebSocket same-origin check |+| `X-Forwarded-Host` | ignored | — |+| `X-Forwarded-Port` | ignored | — |++This means:++- **Your proxy must set `X-Forwarded-Proto`.** Without it, a TLS-terminating+ proxy makes LDR think the request is plain HTTP — secure cookies and HSTS are+ withheld and the same-origin WebSocket check rejects the browser's `https`+ origin.+- **Set `X-Forwarded-For`** so client IPs (and rate limiting) are correct;+ otherwise every request is attributed to the proxy.+- **`ProxyFix` is always on and trusts these headers unconditionally.** If LDR+ is reachable directly (not only via the proxy), a client can forge+ `X-Forwarded-For` (to spoof its IP and evade rate limiting) or+ `X-Forwarded-Proto: https` (to force secure cookies over plaintext). This is+ why LDR must be bound to loopback / an internal network. See Flask's+ [Tell Flask it is behind a proxy](https://flask.palletsprojects.com/en/stable/deploying/proxy_fix/).+- **Exactly one proxy hop is supported.** The count is fixed at `1` in the app+ and has no env/setting knob, so a multi-proxy chain or a CDN/Cloudflare Tunnel+ *in addition* to your proxy is not supported without a code change (LDR would+ read the inner proxy's address as the client IP).+- **HSTS and HTTPS redirect:** LDR sends `Strict-Transport-Security`+ (`max-age=31536000; includeSubDomains`, no `preload`) itself on HTTPS+ requests, so don't add a duplicate at the proxy. Do add an HTTP→HTTPS redirect+ at the proxy (shown below).++## nginx++```nginx+# --- in the http { } context (e.g. conf.d/), shared by all servers ---+# Map for the WebSocket upgrade; also lets Socket.IO's long-polling fallback+# (which sends no Upgrade header) keep the connection alive.+map $http_upgrade $connection_upgrade {+ default upgrade;+ '' close;+}++# Redirect HTTP to HTTPS+server {+ listen 80;+ server_name ldr.example.com;+ return 301 https://$host$request_uri;+}++server {+ listen 443 ssl;+ http2 on; # `listen ... http2` is deprecated since nginx 1.25.1+ server_name ldr.example.com;++ # Example paths from certbot/Let's Encrypt; see https://certbot.eff.org/instructions+ ssl_certificate /etc/letsencrypt/live/ldr.example.com/fullchain.pem;+ ssl_certificate_key /etc/letsencrypt/live/ldr.example.com/privkey.pem;++ # nginx's default is 1 MB, which would 413 every research-library upload.+ # Size this to your upload cap (LDR_SECURITY_UPLOAD_MAX_FILE_SIZE_MB,+ # default 3072 MB per file). Lower both together to tighten the limit.+ client_max_body_size 3072m;++ # Compression LDR no longer does in-process (ADR-0005). For Brotli, add the+ # ngx_brotli module (https://github.com/google/ngx_brotli). nginx ALWAYS+ # compresses text/html regardless of gzip_types — that's fine here because+ # LDR's CSRF token is masked per render (see ADR-0005). application/json is+ # left out so secret-bearing API responses aren't compressed.+ gzip on;+ gzip_vary on;+ gzip_proxied any;+ gzip_types text/css text/javascript application/javascript image/svg+xml;++ location / {+ proxy_pass http://127.0.0.1:5000;+ proxy_http_version 1.1;+ proxy_set_header Host $host;+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;+ proxy_set_header X-Forwarded-Proto $scheme; # required for HTTPS/cookies/HSTS++ # LDR streams live progress as Server-Sent Events on these routes;+ # don't buffer or time them out during a long research run.+ proxy_buffering off;+ proxy_read_timeout 300s;+ proxy_send_timeout 300s;+ }++ # WebSocket (live research progress) needs the HTTP/1.1 upgrade headers.+ location /socket.io {+ proxy_pass http://127.0.0.1:5000;+ proxy_http_version 1.1;+ proxy_set_header Host $host;+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;+ proxy_set_header X-Forwarded-Proto $scheme;+ proxy_set_header Upgrade $http_upgrade;+ proxy_set_header Connection $connection_upgrade;+ proxy_buffering off;+ proxy_read_timeout 3600s; # generous; keeps idle WebSockets open+ }+}+```++Content-hashed bundles under `/static/dist/` are sent with+`Cache-Control: public, max-age=31536000, immutable` (the cache key is the+content hash in the *filename*, e.g. `app.<hash>.js`), so browsers cache them+without revalidating. Don't add `proxy_cache` to `location /`: LDR is a+multi-user app with per-user encrypted databases, and caching authenticated+pages there would leak one user's data to another.++References:+[proxy module](https://nginx.org/en/docs/http/ngx_http_proxy_module.html) ·+[`client_max_body_size`](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) ·+[gzip module](https://nginx.org/en/docs/http/ngx_http_gzip_module.html) ·+[WebSocket proxying](https://nginx.org/en/docs/http/websocket.html) ·+[`http2`](https://nginx.org/en/docs/http/ngx_http_v2_module.html) ·+[Flask-SocketIO deployment](https://flask-socketio.readthedocs.io/en/latest/deployment.html)++## Caddy++Caddy auto-provisions TLS, redirects HTTP→HTTPS, sets `X-Forwarded-For`/`-Proto`+on [`reverse_proxy`](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy)+automatically, and upgrades WebSockets transparently — so the whole deployment+is a few lines:++```caddy+ldr.example.com {+ encode gzip # compression LDR no longer does (ADR-0005)+ reverse_proxy 127.0.0.1:5000+}+```++[Automatic HTTPS](https://caddyserver.com/docs/automatic-https) requires+`ldr.example.com` to be a real public domain whose DNS points at the host, with+inbound ports 80 and 443 reachable for the ACME challenge and a writable data+directory. For an internal/non-public hostname Caddy falls back to its+locally-trusted internal CA (browsers warn unless you trust its root).++## Notes++- **Single backend only.** LDR doesn't support horizontal scaling — multiple+ replicas would need Socket.IO sticky sessions and a shared message queue.+- **Lock down registration** if you expose LDR publicly: it ships its own auth,+ but `LDR_APP_ALLOW_REGISTRATIONS` defaults to **true** (open self-signup). Set+ `LDR_APP_ALLOW_REGISTRATIONS=false` after creating your accounts. Proxy-level+ basic-auth is usually unnecessary given the built-in auth.+- **Other proxies:** Traefik (set its forwarded-headers trusted IPs),+ [Nginx Proxy Manager](unraid.md), or a tunnel. Note **Cloudflare Tunnel adds a+ second hop**, which conflicts with the fixed one-proxy trust model above.++## Related++- [ADR-0005: Reject in-app response compression](../decisions/0005-reject-inapp-response-compression.md)+- WebSocket / Socket.IO behind a proxy, CSRF/cookie issues: [troubleshooting](../troubleshooting.md)+- Cross-origin front-ends, allowed WebSocket/CORS origins: [env configuration](../env_configuration.md)+- [Unraid + Nginx Proxy Manager](unraid.md)diff --git a/docs/troubleshooting.md b/docs/troubleshooting.mdindex c77af3a8de..acee244744 100644--- a/docs/troubleshooting.md+++ b/docs/troubleshooting.md@@ -333,22 +333,25 @@ python -m local_deep_research.web_search_engines.rate_limiting export --format c3. **For reverse proxy setups:**```nginx- # Nginx example+ # Nginx example (see docs/deployment/reverse-proxy.md for the full config)location /socket.io {- proxy_pass http://localhost:5000;+ proxy_pass http://127.0.0.1:5000; # not "localhost" — may resolve to ::1 firstproxy_http_version 1.1;proxy_set_header Upgrade $http_upgrade;proxy_set_header Connection "upgrade";proxy_set_header Host $host;+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;# Required when terminating TLS at the proxy: without X-Forwarded-Proto# the same-origin WebSocket check (the default) sees http:// and rejects# the browser's https Origin. Also needed for secure cookies / HSTS.proxy_set_header X-Forwarded-Proto $scheme;- proxy_set_header X-Forwarded-Host $host;proxy_read_timeout 86400;}```+ See [Deploying behind a reverse proxy](deployment/reverse-proxy.md) for the+ complete nginx/Caddy configuration (uploads, redirects, SSE timeouts).+---## Docker Issues