Local Deep Research on Unraid

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

   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).

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:

   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:

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:

Service Connection Variables

Configure these based on your setup:

Optional LLM Configuration

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

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 Unraid shares (documents, notes, etc.):

For Template Installation (Method 1):

1. Edit the container
2. Add Path mappings under volume configuration:
   • Container Path: /local_collections/personal_notes → Host Path: /mnt/user/documents/personal (Read-only)
   • Container Path: /local_collections/project_docs → Host Path: /mnt/user/documents/projects (Read-only)
   • Container Path: /local_collections/research_papers → Host Path: /mnt/user/papers (Read-only)
3. Apply changes and restart

For Docker Compose Installation (Method 2):

1. Edit docker-compose.unraid.yml
2. Uncomment the document collection lines and adjust paths:

   - /mnt/user/documents/personal:/local_collections/personal_notes:ro
   - /mnt/user/documents/projects:/local_collections/project_docs:ro
   

3. Run Compose Down then Compose Up to apply changes

These paths will then be available in LDR's WebUI Settings for searching.

🎯 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:

nano /etc/docker/daemon.json

Add this configuration:

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

Restart Docker:

/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

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

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

   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:

docker exec -it local-deep-research wget -O- http://localhost:5000

GPU Not Detected in Ollama

Verify driver installation:

nvidia-smi

Check container runtime:

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:

   docker exec -it ollama_service ollama pull gemma3:12b
   

3. Check download progress:

   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:

• LLM Configuration
• Search Engine Configuration

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

📚 Additional Resources

• Main Documentation: https://github.com/LearningCircuit/local-deep-research
• API Documentation: docs/api-quickstart.md
• FAQ: docs/faq.md
• Discord Support: https://discord.gg/ttcqQeFcJ3
• Unraid Forums: Support Thread (to be created)

❓ Getting Help

1. Check logs first:

   docker logs local-deep-research
   docker logs ollama_service
   docker logs searxng
   

2. Search existing issues: GitHub Issues

3. Ask for help:

   • Discord Server
   • GitHub 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!)