learningcircuit--local-deep-research/docs/docker-compose-guide.md

# Docker Compose Guide

This guide covers Docker Compose setup for Local Deep Research. For the quickest start, see the [Quick Start](#quick-start) section below.

## Quick Start

### CPU-Only (All Platforms)

Works on macOS (M1/M2/M3/M4 and Intel), Windows, and Linux:

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

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

**Prerequisites for GPU:** Install the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) first. For step-by-step Ubuntu/Debian install commands, see the [Installation Guide](installation.md#docker-compose-recommended).

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

## Using a Different Model

Specify a model with the `LDR_LLM_MODEL` environment variable:

```bash
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](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_DIR` or API keys.
>
> **Note:** Empty environment variables (e.g., `LDR_LLM_PROVIDER=` or `LDR_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 key, set it to any non-empty invalid value (e.g., `DISABLED`).

| 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. |
| `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:

```yaml
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.yml` are intentionally minimal:
> - **`nofile` (file descriptors):** Not set. Docker's daemon default (typically 1M+) is appropriate. Setting a lower value can cause `unable to open database file` errors under load.
> - **`memlock`:** Set to unlimited so SQLCipher's `mlock()` (a system call that prevents memory from being swapped to disk) can lock encryption keys in RAM when `cipher_memory_security` is enabled (opt-in, off by default).
> - To customize, use a `docker-compose.override.yml` for 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:

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

```bash
docker compose -f docker-compose.default.yml up -d
```

## Using External LLM Providers

### OpenRouter (100+ Models)

```yaml
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)

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

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

## 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_MODEL` environment 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`

## Related Documentation

- [Installation Guide](installation.md)
- [Environment Configuration](env_configuration.md)
- [Full Configuration Reference](CONFIGURATION.md)
- [SearXNG Setup](SearXNG-Setup.md)
- [Unraid Deployment](deployment/unraid.md)
- [Architecture - Resource Lifecycle](architecture.md#thread--resource-lifecycle)