learningcircuit--local-deep-research/docs/deployment/unraid.md

# Local Deep Research on Unraid

This guide covers deploying Local Deep Research (LDR) on Unraid servers.

## 📋 Prerequisites

- **Unraid 6.9 or higher**
- **Docker enabled** in Unraid settings (default)
- **Minimum 20GB storage** (more if using local LLMs)
- **Community Applications plugin** installed (recommended)
- **Optional: NVIDIA GPU** for local LLM acceleration

## 🚀 Installation Methods

### Method 1: Using Unraid Template (Recommended)

This is the easiest method for Unraid users.

#### Step 1: Add Template Repository

1. Navigate to **Docker** tab in Unraid WebUI
2. Click on **Docker Repositories** (at the bottom)
3. Add this URL to **Template repositories**:
   ```
   https://github.com/LearningCircuit/local-deep-research
   ```
4. Click **Save**

#### Step 2: Install Local Deep Research

1. Go back to **Docker** tab
2. Click **Add Container**
3. In the **Template** dropdown, select **LocalDeepResearch**
4. Review the configuration (see [Configuration](#-configuration) section below)
5. Click **Apply**

#### Step 3: (Optional) Install Companion Containers

For local LLM and search capabilities, you'll also need:

**Install Ollama (for local LLM):**
1. Add Container → Search "ollama" in Community Applications
2. Use `/mnt/user/appdata/local-deep-research/ollama` for config path
3. Optional: For container communication, create custom network first:
   ```bash
   docker network create ldr-network
   ```
   Then add to Extra Parameters: `--network=ldr-network`
4. Apply

**Install SearXNG (for local search):**
1. Add Container → Search "searxng" in Community Applications
2. Use `/mnt/user/appdata/local-deep-research/searxng` for config path
3. Optional: If using custom network from above, add to Extra Parameters: `--network=ldr-network`
4. Apply

### Method 2: Docker Compose Manager Plugin

If you prefer docker-compose for multi-container setups:

#### Step 1: Install Docker Compose Manager

1. Go to **Apps** tab
2. Search for "Docker Compose Manager"
3. Click **Install**

#### Step 2: Create Stack from Repository

1. Navigate to **Docker** tab, scroll to **Compose** section
2. Click **Add New Stack**
3. Name it `local-deep-research`
4. Set **Repository URL**:
   ```
   https://github.com/LearningCircuit/local-deep-research.git
   ```
5. Set **Compose File**:
   ```
   docker-compose.yml:docker-compose.unraid.yml
   ```
6. **Branch:** `main`
7. Click **Save** and **Compose Up**

That's it! The stack will automatically use Unraid-appropriate paths. No manual configuration needed.

**For GPU Support:** Change **Compose File** to:
```
docker-compose.yml:docker-compose.unraid.yml:docker-compose.gpu.override.yml
```

**For Document Collections:** After initial setup, edit `docker-compose.unraid.yml` in the stack to uncomment your document paths (see [Using Local Documents](#-using-local-documents)).

**Important Note:** Containers installed with Docker Compose Manager have limited GUI integration. Updates must be done via the "Update Stack" button in the Compose section, not through the regular Docker UI.

### Method 3: Manual Docker Template

For advanced users who want to customize the template:

1. Download the template:
   ```bash
   wget -O /boot/config/plugins/dockerMan/templates-user/local-deep-research.xml \
     https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/unraid-templates/local-deep-research.xml
   ```

2. Go to **Docker** tab → **Add Container**
3. Select **LocalDeepResearch** from template dropdown
4. Configure and **Apply**

## ⚙️ Configuration

### Volume Mappings

All volumes should be under `/mnt/user/appdata/local-deep-research/` for best practices:

| Container Path | Unraid Path (Recommended) | Purpose | Required |
|----------------|---------------------------|---------|----------|
| `/data` | `/mnt/user/appdata/local-deep-research/data` | User databases, research outputs, cache, logs | Yes |
| `/scripts` | `/mnt/user/appdata/local-deep-research/scripts` | Startup scripts (for Ollama integration) | Yes |
| `/root/.ollama` (ollama) | `/mnt/user/appdata/local-deep-research/ollama` | Downloaded LLM models (5-15GB each) | If using Ollama |
| `/etc/searxng` (searxng) | `/mnt/user/appdata/local-deep-research/searxng` | SearXNG configuration | If using SearXNG |

**Performance Tip:** If your appdata share is set to "cache-only", you can use `/mnt/cache/appdata/local-deep-research/` instead of `/mnt/user/appdata/local-deep-research/` for better performance (bypasses FUSE overhead).

### Port Configuration

**Default Port: 5000**

If port 5000 is already in use on your Unraid server:

1. In the template, change the **Host Port** (left side): `5050:5000`
2. Do **NOT** change the Container Port (right side) or `LDR_WEB_PORT` variable
3. Access WebUI at: `http://[unraid-ip]:5050`

### Environment Variables

#### Required Variables (DO NOT CHANGE)

These are pre-configured in the template and **must not** be modified:

| Variable | Value | Purpose |
|----------|-------|---------|
| `LDR_WEB_HOST` | `0.0.0.0` | Binds to all interfaces for Docker networking |
| `LDR_WEB_PORT` | `5000` | Internal container port (change host port instead) |
| `LDR_DATA_DIR` | `/data` | Internal data directory path |

#### Service Connection Variables

Configure these based on your setup:

| Variable | Default | Description |
|----------|---------|-------------|
| `LDR_LLM_OLLAMA_URL` | `http://ollama:11434` | Use this if Ollama is on `ldr-network`<br>Use `http://[IP]:11434` for external Ollama |
| `LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URL` | `http://searxng:8080` | Use this if SearXNG is on `ldr-network`<br>Configure external search in WebUI otherwise |

#### Optional LLM Configuration

**Leave these EMPTY** unless you want to **LOCK** the configuration (prevents changes via WebUI):

| Variable | Purpose |
|----------|---------|
| `LDR_LLM_PROVIDER` | Force LLM provider (ollama, openai, anthropic, google) |
| `LDR_LLM_MODEL` | Force specific model name |
| `LDR_LLM_OPENAI_API_KEY` | Lock OpenAI API key |
| `LDR_LLM_ANTHROPIC_API_KEY` | Lock Anthropic API key |
| `LDR_LLM_GOOGLE_API_KEY` | Lock Google API key |

> **Important:** Unraid templates create all environment variables even when fields are left blank. Empty values (`""`) are treated as **not set** — they will not override or lock anything. Only non-empty values act as overrides. This means leaving a field blank in the Unraid template is safe and equivalent to not having the variable at all.
>
> **Security note:** Setting an API key variable to an empty string does **not** block or clear it. If a key is already stored in the database, it will still be used even when the env var is empty. To explicitly block a key, set it to any non-empty invalid value (e.g., `DISABLED`).

**Recommendation:** Configure these via the WebUI Settings page instead of environment variables for easier management.

### Network Configuration

**Recommended: Bridge Mode with Custom Network**

For multi-container setup (LDR + Ollama + SearXNG):
- All containers should be on the same network: `ldr-network`
- Add `--network=ldr-network` to Extra Parameters for each container
- Containers can communicate using service names (e.g., `http://ollama:11434`)

**Alternative: Individual Containers**

If running LDR alone with external services:
- Use bridge network (default)
- Point to external services by IP: `http://192.168.1.100:11434`

## 🎮 Using Local Documents

To search your local documents, use the **Collections** system in the Web UI:

1. Open the LDR Web UI and navigate to the **Collections** page
2. Create a new collection (e.g., "Research Papers", "Project Docs")
3. Upload documents directly through the browser — no volume mounts needed
4. Select your collection as a search engine, or use **"Search All Collections"** to search across everything

## 🎯 GPU Acceleration (NVIDIA)

To use NVIDIA GPU with Ollama for faster local LLM inference:

### Step 1: Install NVIDIA Driver Plugin

1. Go to **Apps** tab
2. Search for "Nvidia-Driver"
3. Install the plugin
4. Select appropriate driver version (start with latest, go older if issues occur)
5. Reboot Unraid

### Step 2: Configure Docker for NVIDIA Runtime

Edit `/etc/docker/daemon.json`:

```bash
nano /etc/docker/daemon.json
```

Add this configuration:

```json
{
  "registry-mirrors": [],
  "insecure-registries": [],
  "runtimes": {
    "nvidia": {
      "path": "nvidia-container-runtime",
      "runtimeArgs": []
    }
  }
}
```

Restart Docker:
```bash
/etc/rc.d/rc.docker restart
```

### Step 3: Enable GPU in Ollama Container

**For Template Installation:**
1. Edit Ollama container
2. In **Extra Parameters**, add:
   ```
   --runtime=nvidia
   ```
3. Add environment variables:
   - `NVIDIA_DRIVER_CAPABILITIES=all`
   - `NVIDIA_VISIBLE_DEVICES=all`
4. Apply

**For Docker Compose:**
Uncomment the GPU sections in the compose file shown above.

### Verify GPU is Working

```bash
docker exec -it ollama_service nvidia-smi
```

You should see your GPU listed.

## 💾 Backup and Restore

### Using Unraid's Appdata Backup Plugin

1. Install "CA Appdata Backup / Restore" from Community Applications
2. Add to backup paths:
   ```
   /mnt/user/appdata/local-deep-research/
   ```
3. Schedule regular backups

### Manual Backup

```bash
# Backup data
tar -czf ldr_backup_$(date +%Y%m%d).tar.gz \
  /mnt/user/appdata/local-deep-research/data

# Restore data
tar -xzf ldr_backup_20250120.tar.gz -C /
```

**What to Backup:**
- **Critical:** `/mnt/user/appdata/local-deep-research/data` (user databases, research outputs)
- **Optional:** `/mnt/user/appdata/local-deep-research/ollama` (models can be re-downloaded)
- **Optional:** `/mnt/user/appdata/local-deep-research/searxng` (minimal config)

## 🔍 Troubleshooting

### Settings Don't Persist

**Symptom:** Settings reset after container restart

**Solution:**
1. Check volume mapping is correct: `/mnt/user/appdata/local-deep-research/data:/data`
2. Ensure `LDR_DATA_DIR=/data` is set
3. Verify `/mnt/user/appdata/local-deep-research/data` exists and has write permissions
4. Check Unraid logs: **Tools** → **System Log**

### Container Won't Start

**Check dependencies:**
1. If using `ldr-network`, ensure all containers are on the same network
2. Verify Ollama and SearXNG are running if referenced
3. Check logs:
   ```bash
   docker logs local-deep-research
   ```

**Common issues:**
- Port 5000 conflict → Change host port mapping
- Network not found → Create network manually: `docker network create ldr-network`
- Volume permission errors → Ensure paths exist and are writable

### Can't Access WebUI

**Verify network settings:**
1. Check container is running: **Docker** tab
2. Verify port mapping: Should show `5000:5000` or your custom mapping
3. Access via: `http://[unraid-ip]:5000`
4. Check Unraid firewall settings (if enabled)

**Test container networking:**
```bash
docker exec -it local-deep-research wget -O- http://localhost:5000
```

### GPU Not Detected in Ollama

**Verify driver installation:**
```bash
nvidia-smi
```

**Check container runtime:**
```bash
docker inspect ollama_service | grep -i runtime
```

Should show `"Runtime": "nvidia"`

**Common issues:**
- Wrong driver version → Try older driver in Nvidia-Driver plugin
- Runtime not configured → Check `/etc/docker/daemon.json`
- GPU already in use by VM → Stop VMs using GPU passthrough

### Models Download Slowly or Fail

**For Ollama:**
1. Check disk space: Models are 5-15GB each
2. Download manually:
   ```bash
   docker exec -it ollama_service ollama pull gemma3:12b
   ```
3. Check download progress:
   ```bash
   docker logs -f ollama_service
   ```

### "Update Ready" Always Shows

**This is normal for Docker Compose containers.**

Unraid's native Docker UI doesn't integrate with Docker Compose Manager:
- Ignore the "Update Ready" label
- Update via **Docker** tab → **Compose** section → **Update Stack**

## 🔄 Updates

### Manual Updates

**For Template Installation:**
1. Go to **Docker** tab
2. Click container's icon → **Force Update**
3. Container will restart automatically

**For Docker Compose Installation:**
1. Go to **Docker** tab → **Compose** section
2. Find your `local-deep-research` stack
3. Click **Compose Pull** → **Compose Up**

### Automated Updates (Recommended)

**Using Watchtower:**

Watchtower automatically updates your containers when new images are available.

1. Install from Community Applications: Search "Watchtower"
2. Configure to monitor your containers
3. Set update schedule (default: daily at midnight)

Watchtower will automatically pull new images and restart containers when updates are available.

**Alternative:** Unraid's built-in Docker Auto Update plugin (if enabled in Settings)

## 🌐 Advanced Configuration

### Reverse Proxy (Nginx Proxy Manager)

To access LDR via custom domain on Unraid:

1. Install "Nginx Proxy Manager" from Community Applications
2. Add Proxy Host:
   - **Domain Names:** `ldr.yourdomain.com`
   - **Forward Hostname/IP:** `local-deep-research` (or IP)
   - **Forward Port:** `5000`
   - **Scheme:** `http`
3. Enable SSL if desired

### External LLM and Search Configuration

For configuring external LLM providers or custom search engines, see the main configuration documentation:
- [Full Configuration Reference](../CONFIGURATION.md)

All WebUI settings work identically on Unraid as on other platforms.

## 📚 Additional Resources

- **Main Documentation:** [https://github.com/LearningCircuit/local-deep-research](https://github.com/LearningCircuit/local-deep-research)
- **Configuration Reference:** [CONFIGURATION.md](../CONFIGURATION.md)
- **API Documentation:** [docs/api-quickstart.md](../api-quickstart.md)
- **FAQ:** [docs/faq.md](../faq.md)
- **Discord Support:** [https://discord.gg/ttcqQeFcJ3](https://discord.gg/ttcqQeFcJ3)
- **Unraid Forums:** [Support Thread](https://forums.unraid.net) *(to be created)*

## ❓ Getting Help

1. **Check logs first:**
   ```bash
   docker logs local-deep-research
   docker logs ollama_service
   docker logs searxng
   ```

2. **Search existing issues:** [GitHub Issues](https://github.com/LearningCircuit/local-deep-research/issues)

3. **Ask for help:**
   - [Discord Server](https://discord.gg/ttcqQeFcJ3)
   - [GitHub Discussions](https://github.com/LearningCircuit/local-deep-research/discussions)
   - Unraid Forums (support thread coming soon)

4. **When reporting issues, include:**
   - Unraid version
   - Container version (from Docker tab)
   - Relevant logs
   - Configuration (without API keys!)