~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.
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 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_HOSTis127.0.0.1(loopback only, changed from0.0.0.0in the FastAPI release) and it always serves plain HTTP. That default is what you want behind a proxy on the same host. For Docker — where the container's loopback is not reachable from the host — setLDR_WEB_HOST=0.0.0.0and publish to loopback instead (-p 127.0.0.1:5000:5000), or use an internal network. This matters for security — see the next section. Inside the container the proxy's connections then arrive from the Docker network's gateway, not from127.0.0.1; that gateway is the address to put inLDR_SERVER_FORWARDED_ALLOW_IPS(see below).
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
Changed in the FastAPI release — action required. LDR previously applied Werkzeug's
ProxyFixunconditionally, so forwarded headers were always trusted. Uvicorn now honours forwarded request metadata only when you opt in withTRUST_PROXY_HEADERS=true(true/1/yesare accepted). Without it, the request scheme remains plain HTTP behind a TLS-terminating proxy: the session cookie loses itsSecureflag, HSTS is withheld, and the WebSocket same-origin check rejectshttpsorigins. Set it in the environment of the LDR process (note: noLDR_prefix — it is read at startup, before settings are loaded).Uvicorn only honours forwarded headers from peers listed in
LDR_SERVER_FORWARDED_ALLOW_IPS(LDR's default is"*", any peer — the value LDR previously hard-coded, so it is backward compatible; uvicorn's own default when launched directly is127.0.0.1). With a restricted allow-list, LDR's rate limiter trusts uvicorn's own computed client address wheneverTRUST_PROXY_HEADERS=trueis set — regardless of whether you also setLDR_SERVER_TRUSTED_PROXY_COUNT— and with"*"any client that can reach LDR directly chooses its own key, so restrict this to your proxy's real IP(s) wheneverTRUST_PROXY_HEADERS=trueis set. Existing deployments that only setTRUST_PROXY_HEADERS=truekeep booting after upgrading — LDR logs a startup warning instead of refusing to start. LDR only refuses to start over this if you've also setLDR_SERVER_TRUSTED_PROXY_COUNT(to a positive value) or explicitly setLDR_SERVER_FORWARDED_ALLOW_IPS(including to"*") whileLDR_SERVER_FORWARDED_ALLOW_IPSstill resolves to"*". See "CombiningTRUST_PROXY_HEADERSwithLDR_SERVER_TRUSTED_PROXY_COUNT" further down. The startup warning also names the one behaviour change that can need action on upgrade: a proxy on a public or carrier-grade-NAT address that sendsX-Real-IPwithoutX-Forwarded-Foris no longer trusted for it, so list that proxy's IP address inLDR_SERVER_FORWARDED_ALLOW_IPS(the breaking-change note under "X-Real-IPfallback" there).
Rate-limit client-IP extraction is a separate application-level path. Which
trust mode applies depends first on TRUST_PROXY_HEADERS, independent of
LDR_SERVER_TRUSTED_PROXY_COUNT:
TRUST_PROXY_HEADERS=true(at ANYLDR_SERVER_TRUSTED_PROXY_COUNT, including its default of0/unset): with a restrictedLDR_SERVER_FORWARDED_ALLOW_IPS, LDR never re-parsesX-Forwarded-Foritself whenever that header is present. It trusts uvicorn's own computed client address outright — uvicorn'sProxyHeadersMiddlewarealready ran, as the outermost ASGI layer, before LDR's rate limiter ever saw the request. With the unrestricted default"*", uvicorn's client address is the client-forgeable left-most entry, so the rate limiter keys on the right-most entry instead, as in the default mode below. This is the "combo" mode described in full under "CombiningTRUST_PROXY_HEADERSwithLDR_SERVER_TRUSTED_PROXY_COUNT" below — safety comes entirely fromLDR_SERVER_FORWARDED_ALLOW_IPSbeing restricted to your proxy's real IP(s), not fromLDR_SERVER_TRUSTED_PROXY_COUNT's numeric value, which has no effect at all whileTRUST_PROXY_HEADERSis true. uvicorn'sProxyHeadersMiddlewareonly ever looks atX-Forwarded-For— it has no notion ofX-Real-IPat all — so if a request carries noX-Forwarded-For(or simply omits that header),request.clientis still the raw socket peer once uvicorn has run. LDR's rate limiter then falls back toX-Real-IPitself, but only when that raw direct peer passes the application-level forwarding-trust gate: membership in a restricted, explicitly configuredLDR_SERVER_FORWARDED_ALLOW_IPSwhen one is set (private-ness alone confers no trust then), or when the direct peer is private/loopback (or the test-suite sentinel) and no restricted allow-list is configured. Once a restricted allow-list is configured, no unlisted client — public or private — connecting straight to LDR can pick its own rate-limit bucket by sending its ownX-Real-IP. Without one, the private/loopback test is Python'sipaddressclassification (private, loopback or link-local) with two corrections: an IPv4-mapped peer (::ffff:a.b.c.d) is judged by the IPv4 address it wraps, on every supported Python, and a 6to4 (2002::/16), Teredo (2001::/32) or NAT64 (64:ff9b::/96,64:ff9b:1::/48) peer never counts as private on any Python version, although Python may report some of those addresses as private, depending on the version: such a peer is a remote host arriving through a tunnel relay or translator. The test is still broader than "on your network" (it also accepts ranges such as the RFC 5737 documentation blocks, which are not routed on the public internet), so listing your proxy inLDR_SERVER_FORWARDED_ALLOW_IPSremains the precise configuration.TRUST_PROXY_HEADERSunset/false,LDR_SERVER_TRUSTED_PROXY_COUNT=0(the overall default): readsX-Forwarded-Forwhen the direct peer passes the application-level forwarding-trust gate — private/loopback when no restrictedLDR_SERVER_FORWARDED_ALLOW_IPSis explicitly configured, allow-list membership when one is — so a local proxy works before the uvicorn opt-in — and it takes the right-most entry (the one added by the nearest proxy). This mode is for a single proxy, which must still overwrite both client-IP headers with the address it observed, never pass a client-supplied value through. The one-hop nginx example below does that by setting both to$remote_addr. Overwriting pinsX-Forwarded-Forto a single entry andX-Real-IPto the proxy's own value, and it keeps uvicorn's client address underTRUST_PROXY_HEADERS(the left-most entry) equal to the rate limiter's key (the right-most entry).TRUST_PROXY_HEADERSunset/false, explicit trusted-hop count (LDR_SERVER_TRUSTED_PROXY_COUNT=N,N>0): LDR sees the raw socket peer itself (uvicorn's proxy-header rewriting isn't installed), so it does its own counting: declare exactly how many trusted proxies append toX-Forwarded-Forand LDR reads the entry counting from the right — the one the outermost trusted hop appended — so a client-forged prefix cannot spoof its IP even through a real proxy chain; this is one of the multi-hop configurations in Proxy chains. The counting only runs when the direct peer passes the same application-level forwarding-trust gate as above (private/loopback, or allow-list membership when a restrictedLDR_SERVER_FORWARDED_ALLOW_IPSis explicitly configured). The selected entry is normalised by stripping an observed source port (address:port,[v6]:port— the same forms uvicorn's own forwarded parser accepts), so a proxy that appends the port it observed doesn't hand the same client a fresh bucket on every connection. An invalid or negativeLDR_SERVER_TRUSTED_PROXY_COUNTvalue prevents startup rather than silently falling back. See "CombiningTRUST_PROXY_HEADERSwithLDR_SERVER_TRUSTED_PROXY_COUNT" further down for the different (uvicorn-driven) algorithm that applies instead.
| Forwarded header | Used by LDR? | For |
|---|---|---|
X-Forwarded-For |
yes | client IP for rate limiting; a single proxy overwrites it — for a chain see Proxy chains |
X-Real-IP |
fallback | client IP when X-Forwarded-For is absent in combo/default modes, read only from a trusted peer (one listed in a restricted LDR_SERVER_FORWARDED_ALLOW_IPS, otherwise a private, loopback or link-local one, so a proxy on a public or carrier-grade-NAT address must be listed); count-positive mode requires X-Forwarded-For and falls back to the direct peer when it is absent; overwrite or clear it too |
X-Forwarded-Proto |
with TRUST_PROXY_HEADERS |
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'shttpsorigin. - Default mode: overwrite
X-Forwarded-ForandX-Real-IPwith the address observed by the one trusted proxy. With the overwrite form shown below the header carries a single entry. In the default (LDR_SERVER_TRUSTED_PROXY_COUNT=0) trust mode, LDR's rate limiter keys on the right-mostX-Forwarded-Forentry (the one added by the nearest proxy, also across repeated header lines), so a single appending proxy cannot be steered by a client-supplied prefix either. Overwriting remains the supported configuration: it also pinsX-Real-IP, and underTRUST_PROXY_HEADERSuvicorn takes the left-most entry as the client address, which only the overwrite form makes trustworthy. An entry that is not an IP address (an optional:port, or[IPv6]:port, is accepted and dropped) is ignored, and the key falls back to the request's client address. If that client address is itself not an IP address, every such request shares one fixedunparseable-peerbucket. - More than one proxy: see Proxy chains. The overwrite
rule above is for a single proxy. Behind a chain (CDN → nginx) the default
settings key every client on the outer hop's address — one shared
rate-limit bucket — unless the inner proxy resolves the real client itself
(nginx
realip) and overwrites with it, or every inner proxy appends and you set a multi-hop setting. TRUST_PROXY_HEADERS=truemakes uvicorn trust forwarded request metadata. Only set it when LDR is reachable exclusively through your proxy. If LDR is also reachable directly, a client can forgeX-Forwarded-For(to spoof its IP and evade rate limiting) orX-Forwarded-Proto: https(to force secure cookies over plaintext). This is why LDR must be bound to loopback / an internal network. Without the variable set, forwarded headers from a public peer are ignored by uvicorn, but the rate limiter still honours client-IP headers from a private/loopback peer. That distinction is why the overwrite rule above applies even before you opt in.- Exactly one proxy hop is supported in the default mode.
TRUST_PROXY_HEADERSis a boolean, not a hop count, and withLDR_SERVER_TRUSTED_PROXY_COUNTunset LDR keys on the right-most forwarded entry; Proxy chains covers deployments with more than one proxy. (uvicorn's own client address underTRUST_PROXY_HEADERSwith the unrestricted"*"is the left-most entry; the rate limiter then uses it only as the fallback when the forwarded header it reads carries no usable address, and when that entry is not an IP address either, the sharedunparseable-peerbucket instead.) LDR_SERVER_TRUSTED_PROXY_COUNTapplies only whileTRUST_PROXY_HEADERSis unset/false, and it does not affectX-Forwarded-Proto/scheme trust. How to choose its value, and the firewalling every hop needs, are in Proxy chains.- HSTS and HTTPS redirect: LDR sends
Strict-Transport-Security(max-age=31536000; includeSubDomains, nopreload) itself on HTTPS requests, so don't add a duplicate at the proxy. Do add an HTTP→HTTPS redirect at the proxy (shown below).
Proxy chains
This section is the reference for every deployment with more than one proxy in front of LDR — a CDN, tunnel or cloud load balancer in front of nginx, say. The rest of the documentation, the changelog and LDR's startup warnings only summarise it.
One proxy. It must overwrite X-Forwarded-For and X-Real-IP with
the address it observed (nginx: $remote_addr, as in the nginx example
below). Nothing else is needed: in the default mode the rate limiter keys on
that single entry, provided the proxy connects from a private/loopback
address, or is listed in LDR_SERVER_FORWARDED_ALLOW_IPS when you set that.
Why a chain needs more. By default the rate limiter keys on the
right-most X-Forwarded-For entry — the one written by the proxy nearest to
LDR. In a chain that is the inner proxy, and what it writes is the outer
hop's address: if it appends, the right-most entry is the outer hop's
address; if it overwrites with a plain $remote_addr, that address is the
only entry. Either way every client is keyed on the outer hop and shares one
rate-limit bucket. Repeated login or registration attempts can exhaust that
shared budget and lock everyone out of the whole deployment. Setting
LDR_SERVER_FORWARDED_ALLOW_IPS does not
change this while TRUST_PROXY_HEADERS is unset: the allow-list only decides
which direct peers may send forwarded headers, and the right-most entry is
still the key. Pick one of the two configurations below.
Option 1 — the inner proxy resolves the client itself. Configure the
inner proxy to trust the outer hop and recover the client's address from the
header the outer hop sent, then overwrite both client-IP headers with that
verified address. With nginx this is the
realip module:
# inner nginx, http or server context
set_real_ip_from 198.51.100.0/24; # the outer hop's address(es), nothing wider
real_ip_header X-Forwarded-For;
For a request from a set_real_ip_from address, nginx replaces
$remote_addr with the right-most X-Forwarded-For entry the outer hop sent
(with real_ip_recursive on, the right-most one not itself in
set_real_ip_from — use that, and list every outer address, when the outer
layer is several hops). The unchanged single-proxy directives in the nginx
example below then forward the real client, and LDR's default single-proxy
mode keys on it (so does TRUST_PROXY_HEADERS=true with only the inner proxy
in LDR_SERVER_FORWARDED_ALLOW_IPS) — set no multi-hop setting here (with
LDR_SERVER_TRUSTED_PROXY_COUNT=2, the one-entry header is shorter than the
count and every client is keyed on the inner proxy instead). Without
realip, the inner proxy's $remote_addr is the outer hop's address and you
are back to one shared bucket. set_real_ip_from must list exactly the outer
hop's addresses: any address it covers can name its own client address.
Option 2 — inner proxies append, and LDR is told about the chain. Every
inner proxy appends its peer's address to X-Forwarded-For (nginx's
appending variable in place of the $remote_addr overwrite in the example
below; the outermost proxy may append or overwrite). Appending is not enough
on its own — one of these multi-hop settings is required, or the chain
behaves as in "Why a chain needs more" above:
TRUST_PROXY_HEADERSunset/false: setLDR_SERVER_TRUSTED_PROXY_COUNT=N, whereNis the number ofX-Forwarded-Forentries your proxies add — one per appending hop for an ordinary proxy, so CDN → nginx is2. LDR reads theN-th entry from the right.Nmust be exact: too small keys every client on a proxy's address, too large reads an entry the client wrote itself (or, when the header has fewer thanNentries, keys on the direct peer). The count is only applied when the direct peer is trusted — private/loopback, or listed inLDR_SERVER_FORWARDED_ALLOW_IPSonce that is set — so a proxy that reaches LDR from a public address must be listed there. This setting has no effect whileTRUST_PROXY_HEADERS=true.TRUST_PROXY_HEADERS=true(needed anyway when TLS terminates in front of LDR, for secure cookies, HSTS and the WebSocket origin check): list every hop inLDR_SERVER_FORWARDED_ALLOW_IPS— the inner proxy LDR sees as its direct peer and each outer hop's address as it appears inX-Forwarded-For. uvicorn walks the header from the right and returns the first address that is not listed, so a hop missing from the list is returned as the client and every client behind it shares its bucket.
Load balancers that add more than one entry. Some load balancers append
more than one address — for example the client's address followed by an
address of their own. Treat each added entry like a hop: count all of them
in LDR_SERVER_TRUSTED_PROXY_COUNT, or, with TRUST_PROXY_HEADERS=true,
list the addresses the load balancer adds as well as the one it connects
from. Check your load balancer's documentation for exactly what it appends,
and list it in LDR_SERVER_FORWARDED_ALLOW_IPS if it connects from a public
address.
Every hop must be unreachable directly. LDR can only check its direct
peer. If a client can connect straight to an intermediate proxy (it also has
a public listener, or the firewall only protects the edge), that proxy
records the client's real address at its own position, and every entry to
its left — including the one Option 2 reads — is the client's own text. This
mirrors Werkzeug ProxyFix's documented
limitation.
Firewall every hop so it only accepts connections from the hop in front
of it, not just the edge-facing one.
Combining TRUST_PROXY_HEADERS with LDR_SERVER_TRUSTED_PROXY_COUNT
Setting TRUST_PROXY_HEADERS=true recommends restricting
LDR_SERVER_FORWARDED_ALLOW_IPS to your proxy's IP(s) — required only
if you've also adopted LDR_SERVER_TRUSTED_PROXY_COUNT or set
LDR_SERVER_FORWARDED_ALLOW_IPS explicitly, see below. With a restricted
list it hands client-IP resolution to uvicorn (with "*" the rate limiter
keys on the right-most entry instead); either way LDR's own hop-counting is
never used, whatever LDR_SERVER_TRUSTED_PROXY_COUNT is set to
(including left at its default of 0/unset).
TRUST_PROXY_HEADERS=true makes web/app.py launch uvicorn with
proxy_headers=True, which installs uvicorn's ProxyHeadersMiddleware
as the outermost ASGI layer, wrapping the whole FastAPI app, running
before any of LDR's own code (including the rate limiter) ever sees the
request. For a direct peer matching forwarded_allow_ips (uvicorn's own
--forwarded-allow-ips, which web/app.py sets from
LDR_SERVER_FORWARDED_ALLOW_IPS, default "*" for backward
compatibility), that middleware walks X-Forwarded-For from the
right and rewrites the request's client address to the first entry
that is not itself one of the allow-list's trusted IPs; for a direct
peer that does not match, it leaves the client address untouched (the
real raw socket peer). Because this walk is IP-membership-based rather
than a plain hop count, LDR's rate limiter takes advantage of it:
whenever TRUST_PROXY_HEADERS=true, a restricted
LDR_SERVER_FORWARDED_ALLOW_IPS is configured, and the request carries
an X-Forwarded-For header, it trusts uvicorn's already-computed client
address directly and does not re-parse X-Forwarded-For or apply
LDR_SERVER_TRUSTED_PROXY_COUNT's own counting at all — at any
LDR_SERVER_TRUSTED_PROXY_COUNT, including 0/unset. With the
unrestricted "*" it keys on the right-most entry instead (see the
"*" case below); hop counting does not run in either case.
X-Real-IPfallback. uvicorn'sProxyHeadersMiddlewarerewritesscope["client"]only inside itsif x_forwarded_for_values:branch — it has no concept ofX-Real-IPwhatsoever, in anyLDR_SERVER_FORWARDED_ALLOW_IPSconfiguration. So a request with noX-Forwarded-Forat all leavesrequest.clientas the raw socket peer, exactly as ifTRUST_PROXY_HEADERSwere unset — this is the case for a reverse proxy set up with onlyproxy_set_header X-Real-IP $remote_addrand noX-Forwarded-Fordirective, a common nginx pattern. Such a proxy must still clear anyX-Forwarded-Forthe client sent (in nginx, set that header to"", which drops it; or overwrite it with$remote_addras the example below does): nginx passes request headers through by default, so a client-sent value would reach uvicorn, become the client address, and suppress theX-Real-IPfallback (#6849). Without a fallback, every client behind such a proxy would land in one shared rate-limit bucket. LDR's rate limiter restores that fallback itself: when noX-Forwarded-Foris present, it readsX-Real-IP, but only when the raw direct peer passes the application-level forwarding-trust gate — with a restricted, explicitly configuredLDR_SERVER_FORWARDED_ALLOW_IPSthat means membership in the allow-list (a merely-private peer outside the list gets no trust: it is a direct-connecting client, exactly what the restricted configuration exists to defend against); with no restricted allow-list configured it means private/loopback (or the test-suite'stestclientsentinel) — the same check used by theTRUST_PROXY_HEADERS=falseheuristic above. uvicorn provides no equivalent gate forX-Real-IP, so this check is the only thing standing between an arbitrary direct-connecting client'sX-Real-IPheader and the rate limiter; an untrusted direct peer'sX-Real-IPis always ignored.Breaking change in this release. Before it,
X-Real-IPwas trusted unconditionally wheneverTRUST_PROXY_HEADERS=true. Now, with no restrictedLDR_SERVER_FORWARDED_ALLOW_IPS, it is read only from a private, loopback or link-local peer. If your proxy reaches LDR from any other address — a cloud load balancer, a CGNAT/Tailscale peer in100.64.0.0/10, a public nginx host — and sendsX-Real-IPwithoutX-Forwarded-For, that header is now ignored and every client behind it shares the proxy's single bucket, making the login and registration lockouts deployment-global. SetLDR_SERVER_FORWARDED_ALLOW_IPS=<your proxy's address(es)>(its IP address as LDR sees it) to restore per-client keying.Dual-stack listeners. Matching is by parsed IP address, with no IPv4-mapped normalisation — the same as uvicorn's own
_TrustedHosts. A proxy that reaches a dual-stack listener over IPv6 shows up as::ffff:10.0.0.5, which does not match a plain10.0.0.5entry; list the mapped form (or both) when your listener accepts IPv6.LDR_SERVER_FORWARDED_ALLOW_IPSunset /"*"(any peer trusted) — SPOOFABLE. With"*", uvicorn treats every direct peer as trusted and takes a shortcut: it returns the left-mostX-Forwarded-Forentry verbatim — the one a client fully controls — for any request carrying that header, including one from an attacker connecting directly to LDR, and irrespective of hop count. It does not touch the raw headers, only the derived client address, so this cannot be detected or undone downstream: an attacker who reaches LDR directly gets to choose their own rate-limit bucket outright by sending anyX-Forwarded-Forvalue they like. (LDR's rate limiter keys on the right-most entry in this case, which stops a client behind a single appending proxy from steering its bucket with a forged prefix — but a client connecting directly writes the whole header, right-most entry included.) This is the same exposureTRUST_PROXY_HEADERS=truehas always had, going back to beforeLDR_SERVER_FORWARDED_ALLOW_IPS/LDR_SERVER_TRUSTED_PROXY_COUNTexisted — this release does not make it worse.- Legacy deployments —
TRUST_PROXY_HEADERS=trueset, and neither new variable touched — boot normally, with a startup warning naming the risk and the fix, so upgrading never breaks a pre-existing deployment on its own. - Deployments that have adopted this release's new settings —
LDR_SERVER_TRUSTED_PROXY_COUNTset to a positive value, orLDR_SERVER_FORWARDED_ALLOW_IPSset explicitly (including explicitly to"*") — whileLDR_SERVER_FORWARDED_ALLOW_IPSstill resolves to"*": LDR raises aRuntimeErrorat import time, before uvicorn ever binds a port, and refuses to start. Once you've opted into these settings this is an unconditionally exploitable combination, not merely a risky one, so it fails closed the same way a malformed or negativeLDR_SERVER_TRUSTED_PROXY_COUNTdoes, rather than only logging a warning an operator could miss. - "Resolves to
"*"" means uvicorn's semantics, not the literal string. A list that covers an entire address family is exactly as permissive and is refused (or warned about) identically:0.0.0.0/0,::/0,0.0.0.0/0,::/0, and the same range split into pieces such as0.0.0.0/1,128.0.0.0/1. Once every hop in a chain is trusted, uvicorn falls back to the left-most (forgeable)X-Forwarded-Forentry, so these spell"*"in CIDR. A trailing comma is ignored rather than silently producing an allow-list that matches nothing ("*,"is normalised to"*"before uvicorn is handed it).::/0on its own counts too: wherever the listener accepts IPv6 it trusts every peer arriving over it. So does::ffff:0.0.0.0/96, the IPv4-mapped range every IPv4 peer arrives inside on such a listener.
- Legacy deployments —
LDR_SERVER_FORWARDED_ALLOW_IPSset to your proxy's address(es) — the recommended, safe configuration. Set it to the exact IP(s) of your reverse proxy (comma-separated; same syntax as uvicorn's--forwarded-allow-ips), e.g.LDR_SERVER_FORWARDED_ALLOW_IPS=10.0.0.5. With a restricted list, uvicorn only rewrites the client address for connections that actually arrived from that trusted proxy, by walkingX-Forwarded-Forfor the first entry it doesn't recognise as one of those trusted IPs — an attacker connecting directly to LDR (bypassing the proxy) keeps their real raw socket peer provided every entry inLDR_SERVER_FORWARDED_ALLOW_IPSnames a proxy's exact address, whatever address the attacker themselves connects from (public or private): in restricted mode the allow-list is also the only source of application-level forwarding trust, so the rate limiter's own gates (theX-Real-IPfallback and the hop-count direct-peer check) ignore forwarding headers from any peer outside the list — private-ness alone confers nothing. This guarantee is scoped to exact addresses: a network entry instead trusts every peer inside it (see the warning below), so an attacker whose own address falls inside a broader entry is not "outside the list" and keeps the ability to supply their own client address. The rate limiter keys on uvicorn's computed client address in this mode, validated as an IP address (anything else shares the fixedunparseable-peerbucket). That address is only as trustworthy as the peers on the list: uvicorn takes a listed peer'sX-Forwarded-Forat face value, and when every entry in the header is itself a listed address it returns the left-most one. So a client that reaches LDR from an allow-listed address (the proxy host itself, or any address inside a network entry) chooses its own rate-limit key, just as it chooses the schemeTRUST_PROXY_HEADERSsees. A trusted proxy that sends a trailing empty entry (X-Forwarded-For: 203.0.113.7,) makes uvicorn return the proxy's own address, so every client behind it shares one bucket. This is how to get both HTTPS-behind-proxy detection (onlyTRUST_PROXY_HEADERSprovides secure cookies, HSTS, and the WebSocket same-origin check) and correct multi-hop client-IP resolution at the same time — LDR permits this combination and boots normally (it logs an info line confirming the restricted allow-list rather than raising). Each entry is a peer allowed to pick a client's rate-limit bucket, so list exact addresses: a network entry extends that trust to everything inside it, and an entry uvicorn cannot parse as an IP or a network (a hostname such asnginx, or a CIDR with host bits set such as10.0.0.5/8) is kept as an opaque literal that matches no peer at all. LDR logs a startup warning for each, but does not refuse to start. Not over a unix socket. A request that arrives over a UDS has no peer address at all —request.clientisNone, and the rate limiter substitutes"127.0.0.1"— so with a restricted allow-list that synthetic peer is outside the list and every client behind the proxy lands in a single bucket. Reach LDR over TCP when you setLDR_SERVER_FORWARDED_ALLOW_IPS, or leave the allow-list unset for a UDS deployment (127.0.0.1is private, so the pre-existing heuristic trusts it). List the address LDR sees, not the one the proxy dials. The entry must match the direct peer of the TCP connection as it arrives at LDR. With LDR in Docker and the proxy on the host (the-p 127.0.0.1:5000:5000setup above), the proxy connects to127.0.0.1, but inside the container the connection arrives from the Docker network's gateway (often172.17.0.1on the default bridge; a Compose network has its own, e.g.172.18.0.1). Find it withdocker network inspect <network>(theGatewayfield) and list that address. With a proxy container on the same Docker network, list that container's address, and pin it with a staticipv4_addressso it survives a restart. Listing127.0.0.1here instead matches no peer: uvicorn and the rate limiter then ignore the proxy's headers, every client shares one rate-limit bucket, and the login and registration lockouts become deployment-global. Listing the whole Docker subnet (172.18.0.0/16) works but trusts every container on it, and LDR logs a broad-entry warning for it at every start. Behind a chain whose inner proxies append, list every hop, not just the nearest one — uvicorn trusts by IP membership, not hop count, soLDR_SERVER_TRUSTED_PROXY_COUNTplays no part here; see Proxy chains.- Running LDR behind a different ASGI server (not
ldr-web/web/app.py— e.g. a customgunicorn -k uvicorn.workers.UvicornWorkerinvocation) that already passes its own restricted--forwarded-allow-ipson the command line: setLDR_SERVER_FORWARDED_ALLOW_IPSto that same value too. The startup check above only sees the env var, not your ASGI server's actual CLI flags, so this tells it your deployment is genuinely restricted instead of tripping the"*"failure over an unrelated default. Unless you enable LDR's logging yourself (onlyldr-webdoes), LDR writes its startup warnings about these settings straight to stderr.
For the same-host nginx, Caddy and Traefik examples below, set these
variables in the LDR service environment. The proxy connects over IPv4
loopback. This allow-list trusts any local process connecting from
127.0.0.1, so use it only on a host without untrusted local users:
LDR_WEB_HOST=127.0.0.1
TRUST_PROXY_HEADERS=true
LDR_SERVER_FORWARDED_ALLOW_IPS=127.0.0.1
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 $remote_addr;
proxy_set_header X-Real-IP $remote_addr;
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 /ws/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 $remote_addr;
proxy_set_header X-Real-IP $remote_addr;
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 ·
client_max_body_size ·
gzip module ·
WebSocket proxying ·
http2 ·
python-socketio deployment
Caddy
Caddy auto-provisions TLS, redirects HTTP→HTTPS, sets X-Forwarded-For/-Proto
on reverse_proxy
automatically, and upgrades WebSockets transparently — so the whole deployment
is a few lines:
ldr.example.com {
encode gzip # compression LDR no longer does (ADR-0005)
reverse_proxy 127.0.0.1:5000
}
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).
Traefik (same host, one proxy)
This example uses Traefik's file provider.
Traefik connects to 127.0.0.1:5000, matching the LDR allow-list above. In
Traefik's static configuration, redirect HTTP to HTTPS and load the route below:
# /etc/traefik/traefik.yml
entryPoints:
web:
address: ":80"
http:
redirections:
entryPoint:
to: websecure
websecure:
address: ":443"
providers:
file:
filename: /etc/traefik/ldr.yml
# /etc/traefik/ldr.yml
http:
routers:
ldr:
rule: Host(`ldr.example.com`)
entryPoints: [websecure]
service: ldr
tls: {}
services:
ldr:
loadBalancer:
servers:
- url: http://127.0.0.1:5000
Configure a valid TLS certificate or certificate resolver in Traefik; tls: {}
enables TLS for the route but does not provision a trusted certificate. When
Traefik receives requests directly from clients, leave its
forwardedHeaders.trustedIPs
unset and do not use forwardedHeaders.insecure: Traefik then discards
client-supplied forwarding headers and supplies its own. If another trusted
proxy sits in front of Traefik, list only that proxy's IP/CIDR in Traefik's
forwardedHeaders.trustedIPs, then configure LDR for the resulting chain as
described in Proxy chains. If Traefik and LDR run in separate
containers, use an internal network and put Traefik's address as seen by
LDR in LDR_SERVER_FORWARDED_ALLOW_IPS; container loopback is not shared.
Notes
- Single backend only. LDR doesn't support horizontal scaling — multiple replicas would need Socket.IO sticky sessions and a shared message queue.
- Rate-limit storage. LDR keeps its HTTP rate-limit counters, including
the per-client limit on login requests, in process memory by default, so a
restart resets them and separate processes do not share them. Set
RATE_LIMIT_STORAGE_URIto alimitsstorage URI such asredis://redis-host:6379to keep these counters in a shared backend that survives restarts. The separate per-account lockout after repeated failed passwords stays in process memory either way. Install that backend's client package yourself (redisis not an LDR dependency); if it is missing, startup fails with an error that names the variable. That error and the logs can include the storage URI, and LDR's redaction of credentials in it is best-effort, so do not rely on it to hide a password: keep the URI free of secrets you would not want in a log, or give the backend its credentials another way.RATELIMIT_STORAGE_URL, the name the Flask-based releases read, still works whenRATE_LIMIT_STORAGE_URIis unset. Both are ignored when rate limiting is disabled. Set them in the process environment, not in a.envfile: the rate limiter's library also readsRATELIMIT_STORAGE_URLfrom a.envfile in the working directory, which LDR does not treat as a source of its own settings. - Lock down registration if you expose LDR publicly: it ships its own auth,
but
LDR_APP_ALLOW_REGISTRATIONSdefaults to true (open self-signup). SetLDR_APP_ALLOW_REGISTRATIONS=falseafter creating your accounts. Proxy-level basic-auth is usually unnecessary given the built-in auth. - Other proxies: Nginx Proxy Manager, or a tunnel. With Cloudflare Tunnel,
the Cloudflare edge appends the visitor's address to
X-Forwarded-For, butcloudflareditself does not append anything. Whencloudflaredconnects straight to LDR, that is a single appending hop: useLDR_SERVER_TRUSTED_PROXY_COUNT=1(or leave it unset —cloudflaredon the same host or container network is a private peer, so the default right-most rule already picks the visitor), or, withTRUST_PROXY_HEADERS=true, listcloudflared's own address inLDR_SERVER_FORWARDED_ALLOW_IPS. Do not set a count of 2 for a tunnel-only setup: LDR would then key on the entry to the left of the visitor's address, which the visitor can forge. Only when another proxy (such as nginx) sits betweencloudflaredand LDR is it a two-hop chain (see Proxy chains).
Related
- ADR-0005: Reject in-app response compression
- WebSocket / Socket.IO behind a proxy, CSRF/cookie issues: troubleshooting
- Cross-origin front-ends, allowed WebSocket/CORS origins: env configuration
- Unraid + Nginx Proxy Manager