~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
import threading
import traceback
from loguru import logger
from ..__version__ import __version__
from ..utilities.log_utils import config_logger
from .server_config import load_server_config
def _install_thread_excepthook() -> None:
"""Install a global hook that loudly logs uncaught exceptions on any
thread — including daemon threads — so silent crashes in the queue
processor, APScheduler jobs, or the post-login background thread
surface in logs instead of leaving the app wedged with no signal.
Respects a previously-installed hook if any (chains to it).
"""
previous = threading.excepthook
def _hook(args: threading.ExceptHookArgs) -> None:
# Don't try to log for SystemExit-in-thread; that is intentional.
if issubclass(args.exc_type, SystemExit):
return
try:
tb = "".join(
traceback.format_exception(
args.exc_type, args.exc_value, args.exc_traceback
)
)
thread_name = (
args.thread.name if args.thread is not None else "unknown"
)
logger.error(
f"Uncaught exception on thread {thread_name!r}: "
f"{args.exc_type.__name__}: {args.exc_value}\n{tb}"
)
except Exception:
pass # noqa: silent-exception — last-ditch; the excepthook itself must never crash the interpreter
finally:
# Chain to the previous hook (usually threading's default).
try:
previous(args)
except Exception:
pass # noqa: silent-exception — previous hook failing must not turn our hook into a crash vector
threading.excepthook = _hook
# reraise=True is load-bearing: without it a fatal startup error is logged and
# then SWALLOWED, main() returns None, and the console script exits 0 — so
# systemd `Restart=on-failure` and Kubernetes `restartPolicy: OnFailure` read a
# dead server as a clean shutdown and never restart it. uvicorn loads the app
# eagerly on the workers==1 path, so app-import failures land inside main()
# rather than before it. This PR widened the exposure: _load_secret_key() now
# hard-raises where the Flask app fell back to an ephemeral key. SystemExit
# already propagated (a port conflict correctly exits 3); this makes real
# exceptions behave the same way while keeping loguru's formatted traceback.
@logger.catch(reraise=True)
def main():
"""
Entry point for the web application (ldr-web command).
Launches uvicorn with the FastAPI app.
"""
# Install the excepthook before any other threads are spawned so
# uncaught exceptions in daemon threads (queue processor, APScheduler
# jobs, post-login background thread) surface in logs instead of
# dying silently.
_install_thread_excepthook()
config = load_server_config()
config_logger("ldr_web", debug=config["debug"])
from ..security.process_dump_policy import enforce_process_dump_policy
enforce_process_dump_policy()
logger.info(f"Starting Local Deep Research v{__version__}")
# One-time removal of plaintext legacy RAG docstores (phase 1 of the
# vector-store cutover -- see vector_stores/legacy_cleanup.py). Pure
# filesystem, no DB/login required, so it belongs here at the real
# server-start entrypoint (not in the app factory / lifespan, which the
# test suite exercises without LDR_DATA_DIR isolation -- wiring it there
# would delete a developer's real .pkl files on every test run). Wrapped
# so a cleanup issue never blocks boot; the function logs its own errors
# and is idempotent. Ports #5143.
try:
from ..vector_stores.legacy_cleanup import migrate_legacy_docstores
migrate_legacy_docstores()
except Exception:
logger.exception("Legacy RAG docstore migration failed at startup")
# Ported from main: `web.use_https` never actually served TLS on either
# framework -- main only logged that it is unsupported and told the
# operator to front the app with a reverse proxy. Without this, someone
# who sets LDR_WEB_USE_HTTPS=true gets total silence and reasonably
# assumes TLS is on. Say so plainly instead.
if config.get("use_https"):
logger.warning(
"web.use_https is set, but HTTPS is not served directly. "
"Terminate TLS at a reverse proxy (nginx, Caddy, Traefik) in "
"front of this server; it is listening on plain HTTP."
)
_run_with_uvicorn(config["host"], config["port"], config["debug"])
def _normalise_forwarded_allow_ips(raw: str) -> str:
"""The allow-list string uvicorn is handed for ``raw``.
TWIN of ``web/dependencies/rate_limit.py``'s
``_normalise_forwarded_allow_ips`` -- duplicated rather than
imported because importing that module here would run its
import-time startup guard and freeze its view of the allow-list
before uvicorn has started, and would pull slowapi/limits and the
server config into this launcher. The two are pinned together by
tests/security/test_middleware_and_proxy_trust_fastapi.py::
TestTrustProxyHeadersUvicornWiring::
test_app_and_rate_limit_normalise_identically.
"""
return (
",".join(item.strip() for item in raw.split(",") if item.strip()) or "*"
)
def _run_with_uvicorn(host: str, port: int, debug: bool) -> None:
"""Launch the FastAPI app via uvicorn.
Lifespan-managed startup/shutdown lives in `fastapi_app.py`; this
function only deals with launching the ASGI server. Logging,
log-queue processor lifecycle, scheduler shutdown, and DB
teardown are all handled inside the FastAPI lifespan.
"""
import os
import uvicorn
# When TRUST_PROXY_HEADERS is set (operator is behind nginx/caddy/traefik),
# honor X-Forwarded-Proto / X-Forwarded-For so request.url.scheme reflects
# TLS termination and HSTS + Secure-cookie logic work correctly. Without
# this, the app always sees http:// behind a TLS proxy.
trust_proxy = os.environ.get("TRUST_PROXY_HEADERS", "").lower() in (
"true",
"1",
"yes",
)
# Which direct peers uvicorn's ProxyHeadersMiddleware will trust forwarded
# headers from -- passed straight through to uvicorn's own
# `--forwarded-allow-ips`. Defaults to "*" (any peer) for backward
# compatibility with every deployment that has only ever set
# TRUST_PROXY_HEADERS=true.
#
# This default is exactly what makes TRUST_PROXY_HEADERS=true UNSAFE to
# combine with `web/dependencies/rate_limit.py`'s
# LDR_SERVER_TRUSTED_PROXY_COUNT hop-count mode: with "*", the middleware
# rewrites `scope["client"]` to the client-forgeable left-most
# X-Forwarded-For entry for ANY direct connection, not just ones from the
# real proxy -- poisoning the hop-count logic's fallback-to-direct-peer
# safety net before it ever runs (see rate_limit.py's import-time check).
# Restricting this to the actual reverse-proxy IP(s) closes that hole:
# uvicorn then only rewrites `scope["client"]` for connections whose
# DIRECT peer is one of these addresses, so an attacker connecting
# straight to LDR keeps their real socket peer and the rate limiter's
# trust boundary stays intact. See "Combining TRUST_PROXY_HEADERS with
# LDR_SERVER_TRUSTED_PROXY_COUNT" in docs/deployment/reverse-proxy.md
# for the recommended value here.
#
# Normalised per entry, not as one string: `web/dependencies/
# rate_limit.py` classifies the SAME value and names it in the
# RuntimeError, the startup warning and the info line it logs, so a
# value the two read differently would make every one of those
# messages describe an allow-list uvicorn was never handed. `","`
# used to arrive here as the literal `","` (one entry matching
# nothing, every client in one bucket) while rate_limit.py read it
# as unset.
forwarded_allow_ips = _normalise_forwarded_allow_ips(
os.environ.get("LDR_SERVER_FORWARDED_ALLOW_IPS", "")
)
uvicorn.run(
"local_deep_research.web.fastapi_app:app",
host=host,
port=port,
workers=1, # Required for Socket.IO without Redis message queue
log_level="warning", # uvicorn's own log level; app uses loguru
# No per-request access log. main justified this with an app-level
# request-logging middleware; nothing in the FastAPI app logs a
# request line today, so only explicit app events reach loguru.
access_log=False,
# Don't advertise the server stack. Flask/werkzeug's Server header
# was suppressed on main; uvicorn sends "server: uvicorn" by default,
# which re-introduces the fingerprinting main deliberately removed.
server_header=False,
timeout_keep_alive=5,
# Bound how long we wait for in-flight requests to drain on
# SIGTERM/SIGINT. Without this, uvicorn waits forever for
# long-running streams (research SSE) and the process never exits.
timeout_graceful_shutdown=10,
proxy_headers=trust_proxy,
forwarded_allow_ips=forwarded_allow_ips if trust_proxy else None,
# Cap inbound WebSocket messages at the transport (uvicorn's default
# is 16 MiB). Must equal socketio_asgi.MAX_INBOUND_MESSAGE_BYTES;
# kept as a literal so this launcher does not import the app module
# before uvicorn starts.
ws_max_size=65536,
)
if __name__ == "__main__":
main()