learningcircuit--local-deep-research/docs/installation.md

# Installation

This page gives you copy-pasteable commands for every install method. For deeper configuration, follow the links to the dedicated guides.

**Prerequisites:** [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/) are required for Options 1–3 below (pip users only need Docker for the optional SearXNG container).


## Docker Compose (Recommended)

The easiest way to get started. Bundles LDR, Ollama, and SearXNG in one command.

**CPU-only (all platforms):**

```bash
curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.yml && docker compose up -d
```

**With NVIDIA GPU (Linux only):**

Prerequisites — install the NVIDIA Container Toolkit (Ubuntu/Debian):

```bash
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install nvidia-container-toolkit -y
sudo systemctl restart docker

# Verify installation
nvidia-smi
```

> **Note:** For RHEL/CentOS/Fedora, Arch, or other distributions, see the [NVIDIA Container Toolkit installation guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html).

Then start the stack:

```bash
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
```

**Optional alias for convenience:**

```bash
alias docker-compose-gpu='docker compose -f docker-compose.yml -f docker-compose.gpu.override.yml'
# Then simply use: docker-compose-gpu up -d
```

**Windows (PowerShell):**

```powershell
curl.exe -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.yml
if ($?) { docker compose up -d }
```

**Use a different model:**

```bash
curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.yml && MODEL=gpt-oss:20b docker compose up -d
```

Open http://localhost:5000 after ~30 seconds.

> **Note:** `curl -O` will overwrite existing docker-compose.yml files in the current directory.

**DIY docker-compose:** See [docker-compose.yml](../docker-compose.yml) for a compose file with reasonable defaults. Things you may want to configure: Ollama GPU driver, context length, keep alive duration, and model selection.

For Cookiecutter setup, environment variables, and troubleshooting, see the [Docker Compose Guide](docker-compose-guide.md).

## Docker

Run each container individually for a minimal setup.

**Linux (native Docker Engine):**

```bash
# Step 1: Pull and run SearXNG for optimal search results
docker run -d -p 8080:8080 --name searxng searxng/searxng

# Step 2: Pull and run Ollama
docker run -d -p 11434:11434 --name ollama ollama/ollama
docker exec ollama ollama pull gpt-oss:20b

# Step 3: Pull and run Local Deep Research
docker run -d -p 5000:5000 --network host \
  --name local-deep-research \
  --volume 'deep-research:/data' \
  -e LDR_DATA_DIR=/data \
  localdeepresearch/local-deep-research
```

**Mac / Windows / WSL2 (Docker Desktop):**

`--network host` doesn't work on Docker Desktop — it silently drops the port publish, and `localhost` inside the LDR container no longer reaches the Ollama/SearXNG containers. Drop `--network host`, keep `-p 5000:5000`, and point Ollama and SearXNG at `host.docker.internal` via env vars:

```bash
# Steps 1 and 2 (SearXNG + Ollama) are the same as above.

# Step 3: Pull and run Local Deep Research
docker run -d -p 5000:5000 \
  --name local-deep-research \
  --add-host=host.docker.internal:host-gateway \
  --volume 'deep-research:/data' \
  -e LDR_DATA_DIR=/data \
  -e LDR_LLM_OLLAMA_URL=http://host.docker.internal:11434 \
  -e LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URL=http://host.docker.internal:8080 \
  localdeepresearch/local-deep-research
```

(`--add-host` is a no-op on Mac/Windows where `host.docker.internal` is already auto-injected, but makes the same recipe work on Linux Docker Desktop.)

If you'd rather not pass env vars, you can launch without them and then change the URLs after first login under **Settings → LLM → Ollama URL** and **Settings → Search → SearXNG → Instance URL**. For most users on these platforms, [Docker Compose](#docker-compose-recommended) is simpler — it wires the URLs up automatically via service names.

Open http://localhost:5000 after ~30 seconds.

## Python Package (pip)

Best for developers or users integrating LDR into existing Python projects.

```bash
pip install local-deep-research
```

For full setup (SearXNG, Ollama, SQLCipher), see the [pip Guide](install-pip.md).

## Unraid

Local Deep Research is available as a pre-configured template for Unraid servers with sensible defaults, automatic SearXNG/Ollama integration, and NVIDIA GPU passthrough support.

For full setup instructions, see the [Unraid Guide](deployment/unraid.md).