Skip to content

~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.

41.3 KB
Raw Blame

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_HOST is 127.0.0.1 (loopback only, changed from 0.0.0.0 in 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 — set LDR_WEB_HOST=0.0.0.0 and 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 from 127.0.0.1; that gateway is the address to put in LDR_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 ProxyFix unconditionally, so forwarded headers were always trusted. Uvicorn now honours forwarded request metadata only when you opt in with TRUST_PROXY_HEADERS=true (true/1/yes are accepted). Without it, the request scheme remains plain HTTP behind a TLS-terminating proxy: the session cookie loses its Secure flag, HSTS is withheld, and the WebSocket same-origin check rejects https origins. Set it in the environment of the LDR process (note: no LDR_ 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 is 127.0.0.1). With a restricted allow-list, LDR's rate limiter trusts uvicorn's own computed client address whenever TRUST_PROXY_HEADERS=true is set — regardless of whether you also set LDR_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) whenever TRUST_PROXY_HEADERS=true is set. Existing deployments that only set TRUST_PROXY_HEADERS=true keep booting after upgrading — LDR logs a startup warning instead of refusing to start. LDR only refuses to start over this if you've also set LDR_SERVER_TRUSTED_PROXY_COUNT (to a positive value) or explicitly set LDR_SERVER_FORWARDED_ALLOW_IPS (including to "*") while LDR_SERVER_FORWARDED_ALLOW_IPS still resolves to "*". See "Combining TRUST_PROXY_HEADERS with LDR_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 sends X-Real-IP without X-Forwarded-For is no longer trusted for it, so list that proxy's IP address in LDR_SERVER_FORWARDED_ALLOW_IPS (the breaking-change note under "X-Real-IP fallback" 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 ANY LDR_SERVER_TRUSTED_PROXY_COUNT, including its default of 0/unset): with a restricted LDR_SERVER_FORWARDED_ALLOW_IPS, LDR never re-parses X-Forwarded-For itself whenever that header is present. It trusts uvicorn's own computed client address outright — uvicorn's ProxyHeadersMiddleware already 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 "Combining TRUST_PROXY_HEADERS with LDR_SERVER_TRUSTED_PROXY_COUNT" below — safety comes entirely from LDR_SERVER_FORWARDED_ALLOW_IPS being restricted to your proxy's real IP(s), not from LDR_SERVER_TRUSTED_PROXY_COUNT's numeric value, which has no effect at all while TRUST_PROXY_HEADERS is true. uvicorn's ProxyHeadersMiddleware only ever looks at X-Forwarded-For — it has no notion of X-Real-IP at all — so if a request carries no X-Forwarded-For (or simply omits that header), request.client is still the raw socket peer once uvicorn has run. LDR's rate limiter then falls back to X-Real-IP itself, but only when that raw direct peer passes the application-level forwarding-trust gate: membership in a restricted, explicitly configured LDR_SERVER_FORWARDED_ALLOW_IPS when 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 own X-Real-IP. Without one, the private/loopback test is Python's ipaddress classification (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 in LDR_SERVER_FORWARDED_ALLOW_IPS remains the precise configuration.
  • TRUST_PROXY_HEADERS unset/false, LDR_SERVER_TRUSTED_PROXY_COUNT=0 (the overall default): reads X-Forwarded-For when the direct peer passes the application-level forwarding-trust gate — private/loopback when no restricted LDR_SERVER_FORWARDED_ALLOW_IPS is 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 pins X-Forwarded-For to a single entry and X-Real-IP to the proxy's own value, and it keeps uvicorn's client address under TRUST_PROXY_HEADERS (the left-most entry) equal to the rate limiter's key (the right-most entry).
  • TRUST_PROXY_HEADERS unset/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 to X-Forwarded-For and 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 restricted LDR_SERVER_FORWARDED_ALLOW_IPS is 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 negative LDR_SERVER_TRUSTED_PROXY_COUNT value prevents startup rather than silently falling back. See "Combining TRUST_PROXY_HEADERS with LDR_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's https origin.
  • Default mode: overwrite X-Forwarded-For and X-Real-IP with 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-most X-Forwarded-For entry (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 pins X-Real-IP, and under TRUST_PROXY_HEADERS uvicorn 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 fixed unparseable-peer bucket.
  • 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=true makes 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 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. 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_HEADERS is a boolean, not a hop count, and with LDR_SERVER_TRUSTED_PROXY_COUNT unset LDR keys on the right-most forwarded entry; Proxy chains covers deployments with more than one proxy. (uvicorn's own client address under TRUST_PROXY_HEADERS with 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 shared unparseable-peer bucket instead.)
  • LDR_SERVER_TRUSTED_PROXY_COUNT applies only while TRUST_PROXY_HEADERS is unset/false, and it does not affect X-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, 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).

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_HEADERS unset/false: set LDR_SERVER_TRUSTED_PROXY_COUNT=N, where N is the number of X-Forwarded-For entries your proxies add — one per appending hop for an ordinary proxy, so CDN → nginx is 2. LDR reads the N-th entry from the right. N must 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 than N entries, keys on the direct peer). The count is only applied when the direct peer is trusted — private/loopback, or listed in LDR_SERVER_FORWARDED_ALLOW_IPS once that is set — so a proxy that reaches LDR from a public address must be listed there. This setting has no effect while TRUST_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 in LDR_SERVER_FORWARDED_ALLOW_IPS — the inner proxy LDR sees as its direct peer and each outer hop's address as it appears in X-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-IP fallback. uvicorn's ProxyHeadersMiddleware rewrites scope["client"] only inside its if x_forwarded_for_values: branch — it has no concept of X-Real-IP whatsoever, in any LDR_SERVER_FORWARDED_ALLOW_IPS configuration. So a request with no X-Forwarded-For at all leaves request.client as the raw socket peer, exactly as if TRUST_PROXY_HEADERS were unset — this is the case for a reverse proxy set up with only proxy_set_header X-Real-IP $remote_addr and no X-Forwarded-For directive, a common nginx pattern. Such a proxy must still clear any X-Forwarded-For the client sent (in nginx, set that header to "", which drops it; or overwrite it with $remote_addr as 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 the X-Real-IP fallback (#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 no X-Forwarded-For is present, it reads X-Real-IP, but only when the raw direct peer passes the application-level forwarding-trust gate — with a restricted, explicitly configured LDR_SERVER_FORWARDED_ALLOW_IPS that 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's testclient sentinel) — the same check used by the TRUST_PROXY_HEADERS=false heuristic above. uvicorn provides no equivalent gate for X-Real-IP, so this check is the only thing standing between an arbitrary direct-connecting client's X-Real-IP header and the rate limiter; an untrusted direct peer's X-Real-IP is always ignored.

    Breaking change in this release. Before it, X-Real-IP was trusted unconditionally whenever TRUST_PROXY_HEADERS=true. Now, with no restricted LDR_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 in 100.64.0.0/10, a public nginx host — and sends X-Real-IP without X-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. Set LDR_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 plain 10.0.0.5 entry; list the mapped form (or both) when your listener accepts IPv6.

  • LDR_SERVER_FORWARDED_ALLOW_IPS unset / "*" (any peer trusted) — SPOOFABLE. With "*", uvicorn treats every direct peer as trusted and takes a shortcut: it returns the left-most X-Forwarded-For entry 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 any X-Forwarded-For value 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 exposure TRUST_PROXY_HEADERS=true has always had, going back to before LDR_SERVER_FORWARDED_ALLOW_IPS/LDR_SERVER_TRUSTED_PROXY_COUNT existed — this release does not make it worse.
    • Legacy deployments — TRUST_PROXY_HEADERS=true set, 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_COUNT set to a positive value, or LDR_SERVER_FORWARDED_ALLOW_IPS set explicitly (including explicitly to "*") — while LDR_SERVER_FORWARDED_ALLOW_IPS still resolves to "*": LDR raises a RuntimeError at 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 negative LDR_SERVER_TRUSTED_PROXY_COUNT does, 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 as 0.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-For entry, 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). ::/0 on 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.
  • LDR_SERVER_FORWARDED_ALLOW_IPS set 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 walking X-Forwarded-For for 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 in LDR_SERVER_FORWARDED_ALLOW_IPS names 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 (the X-Real-IP fallback 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 fixed unparseable-peer bucket). That address is only as trustworthy as the peers on the list: uvicorn takes a listed peer's X-Forwarded-For at 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 scheme TRUST_PROXY_HEADERS sees. 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 (only TRUST_PROXY_HEADERS provides 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 as nginx, or a CIDR with host bits set such as 10.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.client is None, 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 set LDR_SERVER_FORWARDED_ALLOW_IPS, or leave the allow-list unset for a UDS deployment (127.0.0.1 is 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:5000 setup above), the proxy connects to 127.0.0.1, but inside the container the connection arrives from the Docker network's gateway (often 172.17.0.1 on the default bridge; a Compose network has its own, e.g. 172.18.0.1). Find it with docker network inspect <network> (the Gateway field) and list that address. With a proxy container on the same Docker network, list that container's address, and pin it with a static ipv4_address so it survives a restart. Listing 127.0.0.1 here 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, so LDR_SERVER_TRUSTED_PROXY_COUNT plays no part here; see Proxy chains.
  • Running LDR behind a different ASGI server (not ldr-web / web/app.py — e.g. a custom gunicorn -k uvicorn.workers.UvicornWorker invocation) that already passes its own restricted --forwarded-allow-ips on the command line: set LDR_SERVER_FORWARDED_ALLOW_IPS to 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 (only ldr-web does), 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_URI to a limits storage URI such as redis://redis-host:6379 to 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 (redis is 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 when RATE_LIMIT_STORAGE_URI is unset. Both are ignored when rate limiting is disabled. Set them in the process environment, not in a .env file: the rate limiter's library also reads RATELIMIT_STORAGE_URL from a .env file 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_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: Nginx Proxy Manager, or a tunnel. With Cloudflare Tunnel, the Cloudflare edge appends the visitor's address to X-Forwarded-For, but cloudflared itself does not append anything. When cloudflared connects straight to LDR, that is a single appending hop: use LDR_SERVER_TRUSTED_PROXY_COUNT=1 (or leave it unset — cloudflared on the same host or container network is a private peer, so the default right-most rule already picks the visitor), or, with TRUST_PROXY_HEADERS=true, list cloudflared's own address in LDR_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 between cloudflared and LDR is it a two-hop chain (see Proxy chains).

Related