~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.
Docker Compose Guide
This guide covers Docker Compose setup for Local Deep Research. For the quickest start, see the Quick Start section below.
Quick Start
CPU-Only (All Platforms)
Works on macOS (M1/M2/M3/M4 and Intel), Windows, and Linux:
curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.yml && docker compose up -d
With NVIDIA GPU (Linux Only)
For hardware-accelerated inference:
curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.yml && \
curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.gpu.override.yml && \
docker compose -f docker-compose.yml -f docker-compose.gpu.override.yml up -d
Prerequisites for GPU: Install the NVIDIA Container Toolkit first. For step-by-step Ubuntu/Debian install commands, see the Installation Guide.
Open http://localhost:5000 after ~30 seconds.
Using a Different Model
Specify a model with the LDR_LLM_MODEL environment variable:
LDR_LLM_MODEL=gemma3:4b docker compose up -d
The model will be automatically pulled if not already available.
Configuration Options
docker-compose.yml
The base configuration includes:
| Service | Description |
|---|---|
local-deep-research |
The main web application (port 5000) |
ollama |
Local LLM inference engine |
searxng |
Privacy-focused meta search engine |
Key Environment Variables
Most settings can be configured through the web UI at http://localhost:5000/settings. Environment variables override UI settings and lock them. For the complete list of all environment variables and their defaults, see CONFIGURATION.md.
⚠️ Warning: Setting environment variables causes a hard override—the setting becomes read-only in the UI and cannot be changed until the environment variable is removed. For settings you may want to adjust later, use the web UI instead. Environment variables are best suited for deployment-specific values like
LDR_DATA_DIRor API keys.Note: Empty environment variables (e.g.,
LDR_LLM_PROVIDER=orLDR_LLM_PROVIDER="") are treated as not set — they will not override anything and the setting remains editable in the UI. This prevents Docker Compose templates with blank fields from accidentally locking settings. Only non-empty values act as overrides. Setting an API key to an empty string does not block or clear it — if a key exists in the database, it will still be used. To explicitly block a stored API key, set its variable to a non-empty placeholder that is not a working key (e.g.,DISABLED); API keys are plain-text settings, so this raises no settings error. Do not use placeholders for typed settings such as numbers, checkboxes or JSON: a value that cannot be converted raises a settings error.
| Variable | Description |
|---|---|
LDR_WEB_HOST |
Bind address (default: 0.0.0.0 for Docker) |
LDR_WEB_PORT |
Internal port (default: 5000) |
LDR_DATA_DIR |
Data directory (default: /data) |
LDR_APP_ALLOW_REGISTRATIONS |
Allow new user registration (default: true). Set to false for public deployments after creating your initial account. |
TRUST_PROXY_HEADERS |
Set to true only when TLS terminates at a reverse proxy in front of LDR. See Reverse proxy configuration. |
LDR_SERVER_FORWARDED_ALLOW_IPS |
With TRUST_PROXY_HEADERS=true: your reverse proxy's IP address(es) as LDR sees them. For a proxy on the Docker host that is the Docker network's gateway (docker network inspect, Gateway), not 127.0.0.1; an address the proxy does not connect from puts every client in one rate-limit bucket. Unset means the rate limiter keys on the right-most X-Forwarded-For entry from any peer, so a client that reaches LDR directly picks its own key (startup warning). Also needed if the proxy connects from a public/CGNAT address: without TRUST_PROXY_HEADERS its forwarded headers are ignored, and with it only its X-Real-IP is; when the header it sends is ignored, all clients behind it share one rate-limit bucket. A single proxy must overwrite X-Forwarded-For and X-Real-IP with the address it observed. Behind a chain (CDN → nginx) the defaults key every client on the outer proxy's address (one shared bucket): see Proxy chains. |
LDR_LLM_PROVIDER |
LLM provider (ollama, openai, anthropic, etc.) |
LDR_LLM_MODEL |
Model name (e.g., gemma3:12b) |
Changing the External Port
Use Docker's port mapping instead of environment variables:
ports:
- "8080:5000" # Expose on port 8080 instead of 5000
Volume Mounts
| Volume | Purpose |
|---|---|
ldr_data |
Application data |
ldr_scripts |
Startup scripts |
ldr_rag_cache |
RAG index cache |
ollama_data |
Downloaded models |
searxng_data |
Search engine config |
Resource Limits
Warning: Resource limits in the base
docker-compose.ymlare intentionally minimal:
nofile(file descriptors): Not set. Docker's daemon default (typically 1M+) is appropriate. Setting a lower value can causeunable to open database fileerrors under load.memlock: Set to unlimited so SQLCipher'smlock()(a system call that prevents memory from being swapped to disk) can lock encryption keys in RAM whencipher_memory_securityis enabled (opt-in, off by default).- To customize, use a
docker-compose.override.ymlfor your deployment.
Local Document Collections
Use the Collections system in the Web UI to manage your local documents. Upload files directly through the Collections page — no volume mounts required.
Advanced: Cookie Cutter Configuration
For more customization, use Cookie Cutter to generate a tailored docker-compose file:
# Install cookiecutter
pip install --user cookiecutter
# Clone the repository
git clone https://github.com/LearningCircuit/local-deep-research.git
cd local-deep-research
# Generate custom configuration
cookiecutter cookiecutter-docker/
Cookie Cutter will prompt you for:
| Option | Description |
|---|---|
config_name |
Name for your configuration |
host_port |
Port to expose (default: 5000) |
host_ip |
IP to bind (default: 0.0.0.0) |
host_network |
Use host networking |
enable_gpu |
Enable NVIDIA GPU support |
enable_searxng |
Include SearXNG service |
Then start with:
docker compose -f docker-compose.default.yml up -d
Cookie Cutter also asks whether to enable Ollama and which model to use. The generated Ollama service starts without any model and nothing downloads it for you, so install the model you chose once after starting the stack. Cookie Cutter prints this command when it finishes:
docker compose -f docker-compose.default.yml exec ollama ollama pull <model>
The generated file also sets LDR_LLM_MODEL to that model, which locks the
model setting in the web UI. Delete that line from the generated file if you
want to choose the model in the UI.
Using External LLM Providers
OpenRouter (100+ Models)
environment:
- LDR_LLM_PROVIDER=openai_endpoint
- LDR_LLM_OPENAI_ENDPOINT_URL=https://openrouter.ai/api/v1
- LDR_LLM_OPENAI_ENDPOINT_API_KEY=<your-api-key>
- LDR_LLM_MODEL=anthropic/claude-3.5-sonnet
LM Studio (Running on Host)
environment:
- LDR_LLM_PROVIDER=lmstudio
- LDR_LLM_LMSTUDIO_URL=http://host.docker.internal:1234/v1
# - LDR_LLM_LMSTUDIO_API_KEY=<api-key-if-required> # optional; leave out for unauth instances
- LDR_LLM_MODEL=<your-loaded-model>
Common Commands
# Start services
docker compose up -d
# Start with GPU support
docker compose -f docker-compose.yml -f docker-compose.gpu.override.yml up -d
# View logs
docker compose logs -f
# Stop services
docker compose down
# Update to latest version
docker compose pull && docker compose up -d
# Remove all data (fresh start)
docker compose down -v
The standard and generated Compose stacks allow 60 seconds for LDR to stop. Uvicorn first gives active requests up to 10 seconds to drain, then the app stops schedulers and the queue dispatcher, flushes logs and closes databases. The GPU and Unraid overrides inherit this grace period from the base stack.
An in-flight scheduler job can take longer than this allowance. Increase
services.local-deep-research.stop_grace_period for deployments that need
more time; Docker sends SIGKILL when the allowance expires. This does not
guarantee that an in-progress research run completes during shutdown.
See Docker's stop grace period reference.
Troubleshooting
Container won't start
- Check logs:
docker compose logs local-deep-research - Ensure port 5000 is available
Ollama model not loading
- Check Ollama logs:
docker compose logs ollama - Verify model name in
LDR_LLM_MODELenvironment variable - Ensure sufficient disk space for model download
GPU not detected
- Verify NVIDIA drivers:
nvidia-smi - Check container toolkit:
docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi