diff --git a/.github/ISSUE_TEMPLATE/unraid-ca-submission.md b/.github/ISSUE_TEMPLATE/unraid-ca-submission.md new file mode 100644 index 000000000..897e95245 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/unraid-ca-submission.md @@ -0,0 +1,123 @@ +--- +name: Unraid Community Applications Submission +about: Track submission of LDR to Unraid Community Applications +title: 'Submit Local Deep Research to Unraid Community Applications' +labels: 'enhancement, unraid, community' +assignees: '' + +--- + +## Overview + +Submit Local Deep Research to the Unraid Community Applications repository to make installation easier for Unraid users. + +## Current Status + +- ✅ Unraid template created (`unraid-templates/local-deep-research.xml`) +- ✅ Comprehensive deployment documentation (`docs/deployment/unraid.md`) +- ✅ README updated with Unraid installation instructions +- ✅ FAQ updated with Unraid troubleshooting +- ⏳ Pending: Community Applications submission + +## Submission Requirements + +According to [selfhosters/unRAID-CA-templates](https://github.com/selfhosters/unRAID-CA-templates), we need: + +### 1. Template File ✅ +- [x] XML template following Unraid format +- [x] Located at: `unraid-templates/local-deep-research.xml` +- [x] All required fields populated (Name, Repository, WebUI, Icon, etc.) +- [x] Port, Path, and Variable configurations complete + +### 2. Documentation ✅ +- [x] Complete setup guide: `docs/deployment/unraid.md` +- [x] Installation instructions in README.md +- [x] FAQ entries for common Unraid issues +- [x] Troubleshooting guidance + +### 3. Support Thread ⏳ +- [ ] Create support thread on Unraid forums +- [ ] Include installation instructions +- [ ] Link to GitHub repo and documentation +- [ ] Provide troubleshooting guidance + +### 4. Testing ⏳ +- [ ] Test template on actual Unraid system (6.9+) +- [ ] Verify all volume mappings work correctly +- [ ] Test with both template and Docker Compose methods +- [ ] Verify settings persistence +- [ ] Test GPU passthrough (if NVIDIA GPU available) +- [ ] Confirm backup/restore procedures + +## Submission Process + +1. **Create Unraid Forum Support Thread** + - Post in [Docker Containers](https://forums.unraid.net/forum/49-docker-containers/) section + - Title: `[Support] Local Deep Research - AI Research Assistant` + - Include installation guide, features, and screenshots + +2. **Submit to Community Applications** + - Fork [selfhosters/unRAID-CA-templates](https://github.com/selfhosters/unRAID-CA-templates) + - Add template file to `/templates` directory + - Submit Pull Request + - Reference support thread in PR description + +3. **Alternative: Create Issue** + - Open issue using "CA Template Request" template + - Provide Docker Hub link: `https://hub.docker.com/r/localdeepresearch/local-deep-research` + - Provide GitHub link: `https://github.com/LearningCircuit/local-deep-research` + - Link to support thread + +## Template Information + +**Docker Hub Repository:** `localdeepresearch/local-deep-research` +**GitHub Repository:** `https://github.com/LearningCircuit/local-deep-research` +**Template File:** `https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/unraid-templates/local-deep-research.xml` +**Icon URL:** `https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docs/assets/logo.png` +**Category:** `Tools: Productivity: Network:Web` +**WebUI:** `http://[IP]:[PORT:5000]` + +## Post-Submission Tasks + +Once template is accepted: + +- [ ] Update README.md to mention Community Applications availability +- [ ] Add "Available in Unraid Community Applications" badge +- [ ] Update Unraid documentation with CA instructions +- [ ] Monitor support thread for user questions +- [ ] Keep template updated with new releases + +## Testing Checklist + +Before submission, verify: + +- [ ] Template installs successfully on fresh Unraid system +- [ ] All paths resolve correctly (`/mnt/user/appdata/...`) +- [ ] WebUI is accessible after installation +- [ ] Multi-container setup works (LDR + Ollama + SearXNG) +- [ ] Settings persist across container restarts +- [ ] GPU passthrough works (if applicable) +- [ ] Updates work correctly +- [ ] Backup/restore procedures function + +## Links + +- **Unraid Template:** `unraid-templates/local-deep-research.xml` +- **Deployment Guide:** `docs/deployment/unraid.md` +- **Submission Repo:** https://github.com/selfhosters/unRAID-CA-templates +- **Template Guidelines:** https://selfhosters.net/docker/templating/templating/ +- **Docker Template Schema:** https://wiki.unraid.net/DockerTemplateSchema + +## Notes + +- Template is ready for immediate use by adding repository URL to Unraid +- Community Applications submission provides wider reach and easier discovery +- Support thread required before CA submission +- Testing on real Unraid hardware highly recommended + +--- + +**Next Steps:** +1. Find someone with Unraid to test the template +2. Create support thread on Unraid forums +3. Submit to Community Applications diff --git a/.github/scripts/file-whitelist-check.sh b/.github/scripts/file-whitelist-check.sh index 31a368ea5..2519f1509 100755 --- a/.github/scripts/file-whitelist-check.sh +++ b/.github/scripts/file-whitelist-check.sh @@ -14,6 +14,7 @@ ALLOWED_PATTERNS=( "\.md$" "\.yml$" "\.yaml$" +"\.xml$" "\.sh$" "\.cfg$" "\.flake8$" diff --git a/.github/workflows/ossf-scorecard.yml b/.github/workflows/ossf-scorecard.yml index c015f9c46..92beb23a2 100644 --- a/.github/workflows/ossf-scorecard.yml +++ b/.github/workflows/ossf-scorecard.yml @@ -41,7 +41,7 @@ jobs: results_file: results.sarif results_format: sarif # Publish results to enable scorecard badges - publish_results: true + publish_results: false - name: Upload OSSF Scorecard results to GitHub Security uses: github/codeql-action/upload-sarif@v4.31.2 @@ -55,38 +55,3 @@ jobs: name: ossf-scorecard-results path: results.sarif retention-days: 90 - - - name: Display OSSF Scorecard summary - if: always() - run: | - { - echo "## OSSF Scorecard Security Analysis" - echo "" - echo "✅ OSSF Scorecard analysis completed" - echo "" - echo "### What is OSSF Scorecard?" - echo "OSSF Scorecard checks your repository for security best practices including:" - echo "- **Branch Protection**: Ensures main branch has protection rules" - echo "- **Code Review**: Checks that code changes are reviewed" - echo "- **Signed Releases**: Verifies releases are cryptographically signed" - echo "- **SAST Tools**: Confirms static analysis tools are enabled" - echo "- **Dependency Updates**: Checks for automated dependency updates" - echo "- **Vulnerability Alerts**: Verifies security alerts are enabled" - echo "- **License**: Ensures repository has a license" - echo "- **CI Tests**: Checks for automated testing" - echo "- **Security Policy**: Verifies SECURITY.md exists" - echo "- **Dangerous Workflows**: Detects potentially dangerous GitHub Actions" - echo "" - echo "📊 **Results:**" - echo "- Detailed results uploaded to GitHub Security tab" - echo "- SARIF file available in artifacts" - echo "" - echo "🔗 **Links:**" - echo "- [Security Tab](https://github.com/${{ github.repository }}/security/code-scanning)" - echo "- [OSSF Scorecard Badge](https://securityscorecards.dev/viewer/?uri=github.com/${{ github.repository }})" - echo "" - echo "💡 **Add Badge to README:**" - echo '```markdown' - echo "[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/${{ github.repository }}/badge)](https://securityscorecards.dev/viewer/?uri=github.com/${{ github.repository }})" - echo '```' - } >> "$GITHUB_STEP_SUMMARY" diff --git a/.pre-commit-hooks/file-whitelist-check.sh b/.pre-commit-hooks/file-whitelist-check.sh index 42a09b848..38db3a1e8 100755 --- a/.pre-commit-hooks/file-whitelist-check.sh +++ b/.pre-commit-hooks/file-whitelist-check.sh @@ -47,6 +47,7 @@ ALLOWED_PATTERNS=( "docs/.*\.(png|jpg|jpeg|gif|svg)$" "docs/.*\.ps1$" "src/local_deep_research/web/static/sounds/.*\.mp3$" + "unraid-templates/.*\.xml$" ) WHITELIST_VIOLATIONS=() diff --git a/README.md b/README.md index c75c28bdb..cf8e210cd 100644 --- a/README.md +++ b/README.md @@ -269,7 +269,41 @@ docker compose -f docker-compose.default.yml up [Docker Compose Guide →](docs/docker-compose-guide.md) -### Option 3: Python Package +### Option 3: Unraid + +**For Unraid users:** + +Local Deep Research is fully compatible with Unraid servers! + +#### Quick Install (Template Method) + +1. Navigate to **Docker** tab → **Docker Repositories** +2. Add template repository: + ``` + https://github.com/LearningCircuit/local-deep-research + ``` +3. Click **Add Container** → Select **LocalDeepResearch** from template +4. Configure paths (default: `/mnt/user/appdata/local-deep-research/`) +5. Click **Apply** + +#### Docker Compose Manager Plugin + +If you prefer using Docker Compose on Unraid: + +1. Install "Docker Compose Manager" from Community Applications +2. Create a new stack with the compose file from this repo +3. Update volume paths to Unraid format (`/mnt/user/appdata/...`) + +**Features on Unraid:** +- ✅ Pre-configured template with sensible defaults +- ✅ Automatic SearXNG and Ollama integration +- ✅ NVIDIA GPU passthrough support (optional) +- ✅ Integration with Unraid shares for document search +- ✅ Backup integration with CA Appdata Backup plugin + +[Complete Unraid Setup Guide →](docs/deployment/unraid.md) + +### Option 4: Python Package ```bash # Step 1: Install the package diff --git a/docker-compose.yml b/docker-compose.yml index 85c0d1dfd..7b2e26754 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -5,12 +5,15 @@ # - macOS (M1/M2/M3/M4 Apple Silicon and Intel) # - Windows # - Linux (with or without GPU) +# - Unraid (via Docker Compose Manager plugin) # # To add NVIDIA GPU acceleration: # docker compose -f docker-compose.yml -f docker-compose.gpu.override.yml up -d # # See docker-compose.gpu.override.yml for GPU setup details. # Future: docker-compose.amd.override.yml will support AMD GPUs. +# +# For Unraid users: See docs/deployment/unraid.md for complete setup guide # ============================================================================ services: @@ -96,6 +99,17 @@ services: volumes: - ldr_data:/data - ldr_scripts:/scripts + # ============================================================================ + # LOCAL DOCUMENT COLLECTIONS (Optional) + # Mount your document directories here to search them with LDR. + # + # For Unraid users, replace paths with your Unraid shares: + # - /mnt/user/documents/personal:/local_collections/personal_notes/:ro + # - /mnt/user/documents/projects:/local_collections/project_docs/:ro + # - /mnt/user/papers:/local_collections/research_papers/:ro + # + # The :ro (read-only) suffix is recommended for safety. + # ============================================================================ - ./local_collections/personal_notes:/local_collections/personal_notes/ - ./local_collections/project_docs:/local_collections/project_docs/ - ./local_collections/research_papers:/local_collections/research_papers/ diff --git a/docs/deployment/unraid.md b/docs/deployment/unraid.md new file mode 100644 index 000000000..f7feb9e96 --- /dev/null +++ b/docs/deployment/unraid.md @@ -0,0 +1,508 @@ +# 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. Set network to `ldr-network` (in 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. Set network to `ldr-network` (in 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 Compose Stack + +1. Navigate to **Docker** tab, scroll to **Compose** section +2. Click **Add New Stack** +3. Name it `local-deep-research` +4. Click **Edit Stack** (gear icon) +5. Paste the docker-compose.yml content (see below) +6. Click **Save Changes** +7. Click **Compose Up** + +**docker-compose.yml for Unraid:** + +```yaml +version: '3.8' + +services: + local-deep-research: + image: localdeepresearch/local-deep-research + container_name: local-deep-research + networks: + - ldr-network + ports: + - "5000:5000" + environment: + - LDR_WEB_HOST=0.0.0.0 + - LDR_WEB_PORT=5000 + - LDR_DATA_DIR=/data + - LDR_LLM_OLLAMA_URL=http://ollama:11434 + - LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URL=http://searxng:8080 + volumes: + - /mnt/user/appdata/local-deep-research/data:/data + - /mnt/user/appdata/local-deep-research/scripts:/scripts + # Optional: Add your document directories + # - /mnt/user/documents/personal:/local_collections/personal_notes:ro + # - /mnt/user/documents/projects:/local_collections/project_docs:ro + # - /mnt/user/documents/papers:/local_collections/research_papers:ro + restart: unless-stopped + + ollama: + image: ollama/ollama:0.12.6 + container_name: ollama_service + networks: + - ldr-network + environment: + - OLLAMA_KEEP_ALIVE=30m + # Set MODEL variable to download on first start + - MODEL=gemma3:12b + volumes: + - /mnt/user/appdata/local-deep-research/ollama:/root/.ollama + - /mnt/user/appdata/local-deep-research/scripts:/scripts + restart: unless-stopped + # Uncomment for NVIDIA GPU (requires nvidia-driver plugin) + # runtime: nvidia + # environment: + # - NVIDIA_DRIVER_CAPABILITIES=all + # - NVIDIA_VISIBLE_DEVICES=all + + searxng: + image: searxng/searxng:2025.10.23-e363db970 + container_name: searxng + networks: + - ldr-network + volumes: + - /mnt/user/appdata/local-deep-research/searxng:/etc/searxng + restart: unless-stopped + +networks: + ldr-network: + driver: bridge +``` + +**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 | +| `/local_collections/*` | `/mnt/user/documents/*` | Your document directories to search | Optional | + +**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`
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`
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 | + +**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.): + +1. In the template, find **Path** configurations for local_collections +2. Map your Unraid shares: + - **Personal Notes:** `/mnt/user/documents/personal` → `/local_collections/personal_notes` + - **Project Docs:** `/mnt/user/documents/projects` → `/local_collections/project_docs` + - **Research Papers:** `/mnt/user/papers` → `/local_collections/research_papers` +3. Set **Access mode** to **Read-only (ro)** for safety +4. These paths will be available in LDR's WebUI Settings + +## 🎯 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 + +### For Template Installation + +1. Go to **Docker** tab +2. Click container's icon → **Force Update** +3. Wait for download +4. Container will restart automatically + +### For Docker Compose Installation + +1. Go to **Docker** tab +2. Scroll to **Compose** section +3. Find your `local-deep-research` stack +4. Click **Compose Pull** (downloads new images) +5. Click **Compose Up** (recreates containers) + +**Automated updates:** +Install "User Scripts" plugin and create a script: +```bash +#!/bin/bash +docker pull localdeepresearch/local-deep-research:latest +docker pull ollama/ollama:latest +docker pull searxng/searxng:latest +# For compose users: +# cd /mnt/user/appdata/local-deep-research +# docker compose pull +# docker compose up -d +``` + +Schedule it to run weekly. + +## 🌐 Advanced Configuration + +### Reverse Proxy (Nginx Proxy Manager) + +To access LDR via custom domain: + +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 + +### Using External LLM Providers + +Instead of local Ollama, use cloud providers: + +1. Access LDR WebUI: `http://[unraid-ip]:5000` +2. Go to **Settings** → **LLM Configuration** +3. Select provider (OpenAI, Anthropic, Google, etc.) +4. Enter API key +5. Save + +**Or** lock via environment variables in template (not recommended): +``` +LDR_LLM_PROVIDER=openai +LDR_LLM_OPENAI_API_KEY=sk-... +LDR_LLM_MODEL=gpt-4 +``` + +### Custom Search Engines + +Configure external search engines via WebUI Settings: +- **Brave Search:** Requires API key +- **Serper API:** Google search via API +- **Tavily:** AI-optimized search +- **SearXNG:** Self-hosted (recommended for privacy) + +## 📚 Additional Resources + +- **Main Documentation:** [https://github.com/LearningCircuit/local-deep-research](https://github.com/LearningCircuit/local-deep-research) +- **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!) diff --git a/docs/faq.md b/docs/faq.md index 4e077dc60..a6a7d1c36 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -388,6 +388,107 @@ docker-compose down docker-compose up -d ``` +## Unraid Deployment + +### How do I install LDR on Unraid? + +**Method 1: Template Repository (Recommended)** +1. Go to **Docker** tab → **Docker Repositories** +2. Add: `https://github.com/LearningCircuit/local-deep-research` +3. **Add Container** → Select **LocalDeepResearch** template +4. Configure and **Apply** + +**Method 2: Docker Compose Manager** +1. Install "Docker Compose Manager" from Community Applications +2. Create new stack with the compose file +3. Update volume paths to `/mnt/user/appdata/local-deep-research/` + +[Complete Unraid Guide →](deployment/unraid.md) + +### Settings don't persist on Unraid + +Check volume configuration: +1. Data volume should map to `/mnt/user/appdata/local-deep-research/data:/data` +2. Verify `LDR_DATA_DIR=/data` is set +3. Ensure `/mnt/user/appdata/local-deep-research/data` exists +4. Check permissions (should be writable) + +If using Docker Compose Manager: +- Volumes are defined in your compose stack +- Settings persist in the mounted `/data` volume + +### Unraid shows "Update Ready" for Docker Compose containers + +This is normal behavior for containers managed by Docker Compose Manager: +- Unraid's Docker UI doesn't fully integrate with Compose containers +- **Ignore the "Update Ready" label** in the Docker tab +- Update via **Docker** tab → **Compose** section → **Update Stack** button +- Never use the regular "Force Update" button for Compose containers + +### How do I search my Unraid shares with LDR? + +Mount your Unraid shares as volumes in the template: + +**For Template Installation:** +1. Edit container → **Add Path** +2. **Container Path**: `/local_collections/documents` +3. **Host Path**: `/mnt/user/documents` (your Unraid share) +4. **Access Mode**: Read-only (recommended) +5. Apply + +**For Docker Compose:** +```yaml +volumes: + - /mnt/user/documents/personal:/local_collections/personal_notes:ro + - /mnt/user/documents/projects:/local_collections/project_docs:ro +``` + +Then configure in LDR WebUI Settings → Document Collections. + +### GPU not working with Ollama on Unraid + +Prerequisites: +1. Install "Nvidia-Driver" plugin from Community Applications +2. Select appropriate driver version (start with latest) +3. Reboot Unraid + +Configure Docker runtime (`/etc/docker/daemon.json`): +```json +{ + "runtimes": { + "nvidia": { + "path": "nvidia-container-runtime" + } + } +} +``` + +Restart Docker: `/etc/rc.d/rc.docker restart` + +Enable in Ollama container: +- **Extra Parameters**: `--runtime=nvidia` +- **Add variables**: `NVIDIA_DRIVER_CAPABILITIES=all` and `NVIDIA_VISIBLE_DEVICES=all` + +Verify: `docker exec -it ollama_service nvidia-smi` + +[Detailed GPU Setup →](deployment/unraid.md#gpu-acceleration-nvidia) + +### Port 5000 already in use on Unraid + +Change the **host port** (left side) in port mapping: +- Instead of `5000:5000`, use `5050:5000` +- Do NOT change container port (right side) or `LDR_WEB_PORT` +- Access at: `http://[unraid-ip]:5050` + +### Can't access LDR WebUI from other devices + +Check network configuration: +1. Verify container is running in **Docker** tab +2. Ensure port mapping is correct (`5000:5000`) +3. Test locally first: `http://[unraid-ip]:5000` +4. Check Unraid firewall if enabled +5. For multi-container setup, ensure all on same network (`ldr-network`) + ## Platform-Specific Issues ### Windows filename errors (#339) diff --git a/unraid-templates/local-deep-research.xml b/unraid-templates/local-deep-research.xml new file mode 100644 index 000000000..f10115a92 --- /dev/null +++ b/unraid-templates/local-deep-research.xml @@ -0,0 +1,53 @@ + + + LocalDeepResearch + localdeepresearch/local-deep-research + https://hub.docker.com/r/localdeepresearch/local-deep-research + bridge + + sh + false + https://github.com/LearningCircuit/local-deep-research/issues + https://github.com/LearningCircuit/local-deep-research + Local Deep Research (LDR) is an AI-powered research assistant that performs systematic research by breaking down complex questions, searching multiple sources in parallel, verifying information across sources, and creating comprehensive reports with proper citations. It runs entirely locally with Ollama + SearXNG for privacy, or can use cloud LLM providers. + +Features: +- Privacy-focused: Run entirely locally with Ollama +- Multiple research modes (Quick Summary, Detailed Research, Report Generation) +- Per-user encrypted databases (SQLCipher with AES-256) +- Real-time progress tracking via WebSocket +- Export to PDF or Markdown +- REST API with authentication +- Analytics dashboard + +This template includes the main LDR service. For full functionality, you may also want to install the companion containers (Ollama and SearXNG) or configure external LLM/search providers. + Tools: Productivity: Network:Web + http://[IP]:[PORT:5000] + https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/unraid-templates/local-deep-research.xml + https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docs/assets/logo.png + --network=ldr-network + + + + Support the project + https://github.com/sponsors/LearningCircuit + Optional: Ollama container for local LLM, SearXNG container for local search + 5000 + /mnt/user/appdata/local-deep-research/data + /mnt/user/appdata/local-deep-research/scripts + + + + 0.0.0.0 + 5000 + /data + http://ollama:11434 + http://searxng:8080 + + + + + + 99 + 100 +