Local Deep Research 2.0.0: Three Upgrade Traps I Hit
Local Deep Research 2.0.0 moves Socket.IO, adds CSRF to the API, and turns one bad environment value into a failure that only shows up on your first research query. Measured on a fresh Docker install.
Local Deep Research 2.0.0 shipped on Friday, 7 November. It's the first major version after a ten-week rebuild of the web layer, from Flask to FastAPI and Uvicorn: 1,010 commits, 40 contributors, 264 routes moved across 18 routers.
I run self-hosted apps for a living, so my question wasn't whether the rewrite is good. It was what breaks when you drop the new image on an old deployment. The release notes answer that in detail. I still found one trap they describe too gently.
Tested on my own VM with throwaway Docker volumes. I have no affiliation with the project, and nothing here is sponsored.
What I actually ran
Three containers on a Debian box with 8 vCPU and 23 GB of RAM:
docker run -d --name ldr \
-p 127.0.0.1:5055:5000 \
-v ldr_data:/data \
-e LDR_DATA_DIR=/data \
localdeepresearch/local-deep-research:2.0.0Image size: 885 MB to download, 3.87 GB on disk. Numbers from the logs and from docker stats:
- Healthy in 27 seconds. First line is
Starting Local Deep Research v2.0.0at 04:37:37.944, and/api/v1/healthanswered 200 at 04:38:04. - 364 MiB of RAM at idle, about 1% of one core.
- SQLCipher is on by default:
SQLCipher available and working - databases will be encrypted. - The image sets
LDR_WEB_HOST=0.0.0.0itself. A pip install binds 127.0.0.1 and needs that variable set by hand.
Trap one: the websocket path moved
Socket.IO now lives at /ws/socket.io. Two curls, one minute:
$ curl -o /dev/null -w '%{http_code}\n' \
'http://127.0.0.1:5055/socket.io/?EIO=4&transport=polling'
404
$ curl -o /dev/null -w '%{http_code}\n' \
'http://127.0.0.1:5055/ws/socket.io/?EIO=4&transport=polling'
200If you terminate TLS on nginx or Traefik, your old location /socket.io block matches nothing now. Pages load, sign-in works, the dashboard looks normal, and research progress stops updating. Updating the proxy rule takes one line. Forgetting it costs an evening of hunting a bug that isn't in the app.
A TLS proxy also needs TRUST_PROXY_HEADERS=true and must be the only route to the backend. If it reaches LDR from a public or carrier-grade address, set LDR_SERVER_FORWARDED_ALLOW_IPS to that address. Otherwise every client behind it shares one rate-limit bucket and one login-lockout counter, so a few failed logins lock out everyone.
Trap two: the API wants a CSRF token now
Version 1.x exempted the programmatic endpoints from CSRF checks. 2.0 doesn't:
$ curl -s -X POST -H 'Content-Type: application/json' \
-d '{"query":"test"}' http://127.0.0.1:5055/api/v1/quick_summary
{"error":"CSRF token missing: fetch /auth/csrf-token first"}That's a 403. On the routes that already checked CSRF, 1.x answered 400 instead. The fix takes two steps in the same cookie jar: sign in, fetch GET /auth/csrf-token, then send the value in an X-CSRFToken header. Multipart uploads need the header too, because a csrf_token form field no longer counts outside a small urlencoded body.
Any cron or script of yours that calls LDR with a session cookie breaks on upgrade day, quietly, with a 403. Uptime checks need a look too: /news/health now wants a login and answers a 302, so point your monitor at /api/v1/health.
Trap three: a bad setting fails your first query
This is the one I'd put in bigger type. Start the container with a single wrong value:
docker run -d --name ldr-bad \
-p 127.0.0.1:5056:5000 -v ldr_bad:/data \
-e LDR_DATA_DIR=/data \
-e LDR_LLM_TEMPERATURE=warm \
localdeepresearch/local-deep-research:2.0.0It starts. Health returns 200. You register a user, sign in, the dashboard renders, the settings page loads. Then you ask your first question:
HTTP 503
{"error":"The research was REFUSED because a configured setting is invalid.
Invalid setting 'llm.temperature' from environment: expected a valid range value",
"reason":"invalid_setting"}Credit where it's due: the message names the key and the source, and it never echoes the value, so a typo in an API key won't end up in a screenshot. Problem is, the container looked healthy the whole time between boot and that error. My health check told me nothing useful.
I'd rather the process refuse to start than accept a query and fail it later. Since this one doesn't, add a settings check to the upgrade runbook: grep the environment for LDR_* keys, and open the settings page once with each account.
A fresh install expects Ollama and SearXNG
On a clean container with nothing configured, the same call returns a bare 500: {"error":"An internal error has occurred. Please try again later."} The real reason only shows up in the log:
ValueError: Ollama model not configured. Please set llm.model in settings
(e.g. 'llama3.1:8b', 'qwen2.5:14b').Default provider is Ollama, so the image assumes a model server next to it. Default search tool is searxng, and DuckDuckGo is gone from 2.0. I pulled the engine list from /settings/api/available-search-engines. It returned 32 engines, and DuckDuckGo wasn't one of them. That matches the release notes, and it explains why the README quickstart starts Ollama and SearXNG in the same breath.
What one question cost me
I pointed it at a cloud model and Wikipedia as the only engine, then asked a single question. The default langgraph-agent strategy made 22 model calls in eight minutes: 31,773 prompt tokens and 4,163 completion tokens. My HTTP client gave up at 90 seconds while the server carried on. When I stopped the container, /history/api returned an empty list, so there was no saved answer to read.
Two lessons from that. Don't run research through the synchronous endpoint from a script: use the UI, which streams progress, or the async start-plus-poll routes. And one keyless engine gives the agent very little to work with. The relevance filter kept 2 of 6 Wikipedia results on each pass, so it kept searching to fill the gap. A local SearXNG instance or a Brave key is what makes this app worth running.
I didn't finish a full research answer in this test, and I'd rather say so. What I measured is the deployment surface, and a half-run still tells you what the machinery costs.
Your backup is not your backup
Every account gets its own encrypted SQLCipher database. After registration, the data directory held:
ldr_user_dfd19dc01cba7ce0.db 4.1 MB
ldr_user_dfd19dc01cba7ce0.db.salt 32 B
ldr_user_dfd19dc01cba7ce0.db-wal 1.4 MB
backups/dfd19dc01cba7ce0/ldr_backup_20261109_044149_wqjyoz9q.db 4.6 MBThe key is the user's password, and LDR doesn't store it. The registration form makes you tick a box saying so before it creates the account. Whoever forgets a password loses that database, and you can't open it either.
The rollback footgun deserves its own warning. Databases written by 2.0 can't be opened by 1.10.7. Start the old image against upgraded data and its first sign-in writes a fresh backup over the newest one in the user's folder, then refuses the login. Pre-migration copies land in encrypted_databases/backups/<user hash>/pre-migration/. Copy that folder outside the data directory after each user's first sign-in on 2.0, before retention deletes it.
What changed between the versions
| Behaviour | 1.x | 2.0.0 |
|---|---|---|
| Socket.IO path | /socket.io | /ws/socket.io |
| Missing CSRF on the API | 400 on session routes, /api/v1 exempt | 403 everywhere, header required |
Invalid LDR_* setting | Silent fallback to the default | 503 that names the key |
| DuckDuckGo engine | Available | Removed |
| Rollback to the old image | Works | Needs a pre-upgrade backup |
What I'd do on the next install
- Pin the
2.0.0tag or its digest instead of:latest. A FastAPI rewrite is the release you don't want arriving unannounced. - Copy the whole
/datadirectory offline before the upgrade, then prove you can restore it. - Add the
/ws/socket.iolocation to the proxy, plusTRUST_PROXY_HEADERS=true, and check everyLDR_*value for its type. A bad number waits until your first research query. - Run one real query after the upgrade and read the history page. A 200 from health only proves the process is alive.
- Run SearXNG before you judge the app. Wikipedia alone isn't a research pipeline.
Frequently asked questions
Does Local Deep Research 2.0.0 need an API key?
No, if you run a model locally. The image defaults to the Ollama provider and needs llm.model set to something like llama3.1:8b. Cloud providers need their own key, one variable each.
Can I roll back to 1.10.7 after upgrading?
Only from a backup taken before the upgrade. The database revisions in 2.0 are one-way, so the old image can't open upgraded data.
The rewrite buys real things: a modern ASGI server, a Stop button that aborts model work mid-run, and a much harder security posture around uploads and egress. The cost lands on the operator in the first hour. Update the proxy path, check your environment values, copy the backups out, and run one query before you call it done.