~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.
Upgrading to the first FastAPI-based major release
This guide covers upgrades from v1.10.7 to the first FastAPI-based major
release. The web-layer change itself adds no database schema migration, but
the release also ships database revisions newer than 0030, the newest
revision v1.10.7 knows. Prepare a matching application and data backup before
upgrading; deploying the old image alone is not a working rollback.
To find the release's newest database revision, run this with the installed release (inside its container for Docker deployments):
python -c "from local_deep_research.database.alembic_runner import get_head_revision; print(get_head_revision())"
Or list the migration files in the release's wheel; the newest revision is the highest-numbered file:
unzip -l local_deep_research-*.whl | grep 'database/migrations/versions/0'
Before upgrading
Review saved library locations, especially on multi-user installations.
research_library.storage_path is now operator-managed. Existing saved paths
and the shipped ~/Documents/LocalDeepResearch/Library default stay in use,
including locations outside LDR_DATA_DIR. User settings saves, imports,
resets and deletes cannot change this path; single-setting API updates and
deletes return 403. Set LDR_RESEARCH_LIBRARY_STORAGE_PATH in the deployment
configuration to override it. Changing that value does not move existing files.
See the configuration reference.
- Record the installed package version or image digest and retain its deployment configuration. Use the selected release's dependencies when upgrading or rolling back; a newer lockfile does not describe the old release.
- Let active research and indexing jobs finish, then stop the application and allow its shutdown to complete.
- Take an offline backup of the complete configured LDR data directory,
including databases and configuration, plus any separately configured
document or vector storage. Verify that a copy can be restored before
changing the production data. Each user database is encrypted with that
user's password, which LDR does not store, so a restored copy opens only
with the password the user had when it was taken. Tell users to keep
their current passwords until a rollback is no longer possible; do not
collect users' passwords yourself.
If
report.enable_file_backupis enabled, this backup also includes plaintext reports inresearch_outputs/. Keep it, and any other offline copies, accessible only to trusted operators. See Report file backups for the new permissions on the live directory. - Review the release's compatibility notes and your reverse-proxy setup.
Socket.IO now uses
/ws/socket.io. A trusted TLS-terminating proxy requiresTRUST_PROXY_HEADERS=trueand must be the only way to reach the backend. Follow the reverse-proxy guide, including its header overwrite requirements and, behind more than one proxy, its proxy chains section. If the proxy connects to LDR from a public or carrier-grade-NAT address (a cloud load balancer, a Tailscale100.64.x.xpeer, a public nginx host), setLDR_SERVER_FORWARDED_ALLOW_IPSto its IP address as LDR sees it before you upgrade. Without a restricted allow-list, LDR now readsX-Real-IPonly from a private, loopback or link-local peer (the previous release read it from any peer), so a proxy that sendsX-Real-IPwithoutX-Forwarded-Foris otherwise keyed on its own address: all its clients share one rate-limit bucket and a few failed logins lock everyone out. WithoutTRUST_PROXY_HEADERS, such a proxy'sX-Forwarded-Foris ignored too.
Invalid configured settings
Managed settings reads and research snapshots now fail when a configured
value cannot be converted to its declared type, or when the setting's type
metadata is unsupported. An invalid environment override no longer falls
back to a saved value or default. Missing optional settings still use their
documented defaults. A variable for a key with no declared setting type, such
as LDR_APP_API_RATE_LIMIT, is still read as the raw string.
Check deployment overrides and saved settings on a restored test copy before
upgrading production. For example, LDR_LLM_TEMPERATURE must contain a number;
correct an invalid override in the deployment configuration, or remove it to
use the saved value or default, then restart the application. The selected
saved value must also be valid. See the configuration reference
for setting names and supported values.
A settings validation error identifies the setting key, its source and a
diagnostic reason without including the configured value. The settings page,
the main page and the research form display it, the settings and
search-engine list APIs return it, the /api/v1 research endpoints return
it in a 503 response whose reason is invalid_setting, and the server log
records it. Use those details to locate the setting. If invalid saved values
or type metadata prevent the settings page from opening, retain the backup
and request a targeted repair using those diagnostics. Startup does not
repair every malformed setting: migration 0031 handles only its
allowlisted legacy cases, and the defaults reconciliation after an upgrade
keeps an invalid saved value, logging a warning that names the key, rather
than replacing it with the default.
If an invalid environment override prevents a bulk settings save from preparing its updated settings response, the save preserves the previous stored values and returns the setting diagnostic. Correct the override before retrying the save.
Upgrade and verify
Install the selected release and start one application process against the intended data directory. Users must sign in again after the restart. Per-user database migrations run when those databases are opened; an application health response alone does not verify every user's upgrade.
The revisions after 0030 repair existing data. For example, revision 0031
repairs an allowlisted set of corrupted legacy settings, deduplicates setting
keys and restores their unique index. Its downgrade is intentionally a no-op:
it cannot reconstruct discarded rows or original values. Treat every revision
after 0030 as one-way and roll back from a backup. A data migration matters
for rollback even when no new application table is added.
Before reopening the service to users, verify on the upgraded installation:
- Sign-in and a representative settings save succeed.
- Existing research reports and uploaded documents remain readable.
- A new research run reaches completion with the configured model and search provider; progress still updates after reconnecting.
- Existing collection searches return results, and an indexing operation completes with the configured embedding provider.
- Shutdown completes and the same data remains usable after restarting.
Review the release notes for custom API-client changes, including the removed legacy news routes and CSRF requirements. See the configuration reference for current settings.
CSRF changes for session-cookie clients making state-changing requests
(POST, PUT, PATCH or DELETE): v1.x exempted the programmatic /api/v1
endpoints (POST /api/v1/quick_summary, /api/v1/generate_report and
/api/v1/analyze_documents) from CSRF checks, so those calls worked with no
token. They are now enforced: keep the same cookie jar, sign in, then fetch
GET /auth/csrf-token and send the returned token in X-CSRFToken. A token
fetched before sign-in is invalid because sign-in resets the session. An absent
or invalid token now returns 403. On every other endpoint, including
POST /api/v1/research/{id}/export/{format}, v1.x already required a token and
answered a failure with 400; that status is now 403.
The token transport also narrowed. v1.x (Flask-WTF) read the token from any
form field, including multipart fields. Now a csrf_token form field is read
only from application/x-www-form-urlencoded bodies of 256 KB or less;
otherwise only the X-CSRFToken or X-CSRF-Token header counts. Multipart
clients, such as file uploads that carried csrf_token as a form part, must
send the header or they now receive 403.
For clients parsing web responses, these date fields now emit ISO 8601 instead
of RFC-822 HTTP dates: timestamp in GET /api/research/{id}/logs, time in
each log entry of GET /history/logs/{id} and GET /history/details/{id}
(log list, database-stored entries), and published_date in
GET /library/api/documents (now YYYY-MM-DD). Malformed numeric
path parameters now return 422 instead of 404. GET /settings without a
trailing slash now returns a 307 redirect to /settings/; request the latter
directly if the client does not follow redirects.
Report file backups
At startup, the web application now sets research_outputs/ under the data
directory to mode 0700 on POSIX systems, whether or not
report.enable_file_backup is enabled. New or rewritten report and metadata
files get mode 0600. Reports saved before the upgrade keep their own modes
until they are rewritten, and from then on other OS accounts cannot open them
through the directory. Access gained earlier is not revoked: a hard link made
while the directory was readable still opens a report that keeps its old
mode, and a file descriptor or working directory that another process
already holds inside the directory keeps working. If other accounts could
read the directory before, check for such links and processes.
This needs a directory that the account running Local Deep Research owns, on
a filesystem that keeps the mode. Docker Desktop bind mounts of Windows
folders, WSL drives such as /mnt/c, CIFS/SMB shares and exFAT often accept
chmod without keeping it, or show another owner. In those cases the
application writes no report files. Reports are still saved in the database,
the server log names the cause, and users who enabled the option see a
warning on the research page. Keep the data directory (LDR_DATA_DIR) on a
Linux filesystem path or a Docker named volume owned by that account, or turn
the option off. On Windows, configure access controls on the data directory
for the application account.
PDFs in the old shared library directory
Library reads no longer fall back from a missing per-user PDF to the old
shared library directory. LDR_RESEARCH_LIBRARY_ALLOW_LEGACY_READ_FALLBACK
has been removed; leaving it set does not restore that behavior. Existing
per-user files and PDFs stored in the user's encrypted database remain
readable. The upgrade does not move or delete legacy files.
If an old PDF becomes unavailable, recover it explicitly:
- Retain the offline backup of the old library and user databases.
- Verify the file's owner from trusted source records or a known backup.
A name such as
pdfs/5.pdfor a matching document/resource ID is not proof: different users can have the same IDs. Leave files with uncertain ownership untouched; do not distribute them to users or copy them into every library. - Provide a verified copy only to its owner. The owner can sign in and use the Library upload flow, selecting database PDF storage to retain the bytes in their encrypted database.
- Verify that the imported PDF opens in that account before removing any backup. Uploading does not automatically repair old research links or document IDs; retain those records and the original backup separately.
Automatic pre-migration backups
When the new release opens a user database that needs migration, normally at
that user's first sign-in after the upgrade, it first tries to write an
encrypted copy of that database to the user's
automatic backup directory,
encrypted_databases/backups/<user hash>/ under the data directory. Only
users whose databases the new release has opened have such a backup. It is
encrypted with that user's password at the time of the upgrade. Do not rely
on it in place of the offline backup.
A failed pre-migration backup does not stop the migration. If the copy
cannot be made, for example because free space in the backup directory is
less than twice the database's size or the copy fails its integrity check,
the release logs a Pre-migration backup failed line and migrates the
database anyway. Look for that line after each user's first sign-in.
Treat a user with no Pre-migration backup created line for that sign-in
as having no pre-migration backup, and rely on the offline backup for that
user's rollback.
If the pre-migration backup fails, that first sign-in can still remove the
user's backups made before the upgrade. A backup that v1.10.7 made of a
database with its own salt has no salt file, so it never passes
verification and does not count as that day's backup: the sign-in's login
backup runs even if v1.10.7 made a backup earlier the same UTC day. If that
login backup succeeds, it is a copy of the upgraded database, and with the
default backup.max_count of 1 it removes all of the user's older
backups. To keep them, raise backup.max_count, or copy them out of the
backup directory, before upgrading.
This pre-migration backup is not durable. Writing it applies the user's
backup.max_count and backup.max_age_days to their older automatic
backups, so with the default backup.max_count of 1 it removes all of
them; if those settings cannot be read before the migration, or are not
whole numbers within the settings' ranges (1 to 30 backups, 1 to 90 days),
it removes none. Later events replace or delete the pre-migration backup
itself. A sign-in adds a login backup only when none of the user's backups
dated the current UTC day passes verification, so only the first sign-in on
each later UTC day adds one; further sign-ins that day add nothing while
that day's backup still passes.
- With the default
backup.max_countof1, the first login backup made on a later UTC day replaces it with a copy of the upgraded database. A sign-in shortly after midnight UTC can do this minutes after the upgrade. - With that default, the first sign-in itself does this if it runs past
midnight UTC: the pre-migration backup is named for the time its export
started, and that sign-in's own login backup, made after the migration,
then falls on a later UTC day. On a large database the export and
migration can take minutes. After each user's first sign-in, check that the file named in
that user's
Pre-migration backup createdlog line still exists; if it does not, the pre-migration backup is already gone and the offline backup is the only rollback source for that user. - With a higher
backup.max_countof N, each of those login backups is added and only the newest N files are kept. Whichever comes first deletes the pre-migration backup: the Nth login backup made after it, which is the user's first sign-in on the Nth later UTC day on which they sign in, however young the backup is, or the first login backup made after it is older thanbackup.max_age_days(default7). - A password change deletes all of that user's backups, this one included, and writes a new backup of the upgraded database.
After any of these, restoring from encrypted_databases/backups/ restores
the upgraded database, not the pre-migration one, and v1.10.7 refuses it.
Copy the pre-migration backups out immediately. Each user's backup is created at that user's own first sign-in, so there is no single moment that covers everyone: copy each user's backup directory to storage outside the data directory immediately after that user's first sign-in on the new release, before their first sign-in on a later UTC day and before any password change.
Raising backup.max_count and backup.max_age_days before upgrading, for
example with the LDR_BACKUP_MAX_COUNT and LDR_BACKUP_MAX_AGE_DAYS
environment variables, only widens that window. The pre-migration backup
then survives until the user's first sign-in on the
backup.max_count-th later UTC day on which they sign in, or until the
first login backup after it is older than backup.max_age_days, whichever
comes first, and a password change still deletes it at any time. With
LDR_BACKUP_MAX_COUNT=5, a user who signs in daily loses it on the fifth
day after the upgrade even if backup.max_age_days is 90; signing in
several times a day does not bring that forward. It is not a substitute for
copying the backups out.
Protect the copies you take, and the offline backup, as you protect the data directory. Each copy opens with the password its user had when it was taken, and keeps doing so after the user changes that password. LDR deletes a user's automatic backups on a password change for that reason, but it cannot reach copies made outside the data directory. Restrict access to them, destroy them once a rollback to v1.10.7 is no longer needed, and destroy a user's copies at once if that user changes a password because it may have been compromised. The offline backup has the same exposure, and that user's rollback then relies on it alone.
Backup file names start with their UTC creation time
(ldr_backup_YYYYMMDD_HHMMSS), and the log records each
Pre-migration backup created path. A backup created before the upgrade is
not a pre-migration backup, and one created at a later sign-in on the new
release is a copy of the upgraded database.
Rekey lock files and "pending maintenance"
The first sign-in of each user on this release creates
ldr_user_<hash>.db.rekey.lock and ldr_user_<hash>.db.rekey.epoch next to
the user's database in encrypted_databases/; a password change also uses
ldr_user_<hash>.db.rekey.pending while it runs. Include them when you copy
a user's database files, and keep the server user able to create and write
files in that directory. A login answered with "Your account database is
pending maintenance" (HTTP 503) means one of these files could not be read,
written or locked. The
rekey recovery guide explains the log lines
and how to recover with the server stopped.
Rollback
Never start v1.10.7 against the upgraded data directory. v1.10.7 knows
revisions only through 0030. Each sign-in with the correct password against
a database stamped with a newer revision first makes a forced backup and keeps
only the newest backup file for that user. That replaces the user's automatic
pre-migration backup with a copy of the upgraded database. Then v1.10.7
refuses the login with Can't locate revision identified by '<revision>'.
- Stop the upgraded application.
- Before any downgrade attempt, copy every user's backups from
encrypted_databases/backups/to storage outside the data directory, if you have not already copied the pre-migration backups. Preserve the upgraded data separately as well if post-upgrade work needs later recovery. - Restore the verified pre-upgrade offline backup. If you have none, restore
each migrated user's database from the pre-migration backup you copied
out after the upgrade; see the
database backup guide. A user whose
first sign-in logged
Pre-migration backup failed, or noPre-migration backup createdline, has no pre-migration backup to restore from. Check each file's timestamp first: a backup taken now fromencrypted_databases/backups/is a copy of the upgraded database if a later daily backup or a password change has replaced the pre-migration one, and v1.10.7 refuses it. A database the new release never opened was not migrated and needs no restore. Accounts created on the new release have no pre-upgrade copy: the offline backup does not contain them, and v1.10.7 refuses their databases, which the new release created at its newest revision. Export anything those users need before rolling back. After the restore, each user signs in with the password they had when the restored copy was taken. - Deploy the matching previous application version and configuration.
Do not run the old and new versions against the same writable data directory. Work saved after the backup will not be present in that restored copy. Manually changing the revision marker or invoking the no-op downgrades does not restore the previous data; use the backup for this rollback procedure.
Restore custom Socket.IO clients and proxy rules to /socket.io. If you adopted
RATE_LIMIT_STORAGE_URI, also restore or retain RATELIMIT_STORAGE_URL for the
old release. Keep the backend isolated behind the proxy. Users must sign in
again, and interrupted work may need to be restarted.