diff --git a/netgrimoire-agent.md b/netgrimoire-agent.md new file mode 100644 index 0000000..3de2af4 --- /dev/null +++ b/netgrimoire-agent.md @@ -0,0 +1,503 @@ +--- +title: Ollama with agent +description: The smart home reference +published: true +date: 2026-02-18T22:14:41.533Z +tags: +editor: markdown +dateCreated: 2026-02-18T22:14:41.533Z +--- + +# AI Automation Stack - Ollama + n8n + Open WebUI + +## Overview + +This stack provides a complete self-hosted AI automation solution for homelab infrastructure management, documentation generation, and intelligent monitoring. The system consists of four core components that work together to provide AI-powered workflows and knowledge management. + +## Architecture + +``` +┌─────────────────────────────────────────────────┐ +│ AI Automation Stack │ +│ │ +│ Open WebUI ────────┐ │ +│ (Chat Interface) │ │ +│ │ │ │ +│ ▼ ▼ │ +│ Ollama ◄──── Qdrant │ +│ (LLM Runtime) (Vector DB) │ +│ ▲ │ +│ │ │ +│ n8n │ +│ (Workflow Engine) │ +│ │ │ +│ ▼ │ +│ Forgejo │ Wiki.js │ Monitoring │ +└─────────────────────────────────────────────────┘ +``` + +## Components + +### Ollama +- **Purpose**: Local LLM runtime engine +- **Port**: 11434 +- **Resource Usage**: 4-6GB RAM (depending on model) +- **Recommended Models**: + - `qwen2.5-coder:7b` - Code analysis and documentation + - `llama3.2:3b` - General queries and chat + - `phi3:mini` - Lightweight alternative + +### Open WebUI +- **Purpose**: User-friendly chat interface with built-in RAG (Retrieval Augmented Generation) +- **Port**: 3000 +- **Features**: + - Document ingestion from Wiki.js + - Conversational interface for querying documentation + - RAG pipeline for context-aware responses + - Multi-model support +- **Access**: `http://your-server-ip:3000` + +### Qdrant +- **Purpose**: Vector database for semantic search and RAG +- **Ports**: 6333 (HTTP), 6334 (gRPC) +- **Resource Usage**: ~1GB RAM +- **Function**: Stores embeddings of your documentation, code, and markdown files + +### n8n +- **Purpose**: Workflow automation and orchestration +- **Port**: 5678 +- **Default Credentials**: + - Username: `admin` + - Password: `change-this-password` (⚠️ **Change this immediately**) +- **Access**: `http://your-server-ip:5678` + +## Installation + +### Prerequisites +- Docker and Docker Compose installed +- 16GB RAM minimum (8GB available for the stack) +- 50GB disk space for models and data + +### Deployment Steps + +1. **Create directory structure**: +```bash +mkdir -p ~/ai-stack/{n8n/workflows} +cd ~/ai-stack +``` + +2. **Download the compose file**: +```bash +# Place the ai-stack-compose.yml in this directory +wget [your-internal-url]/ai-stack-compose.yml +``` + +3. **Configure environment variables**: +```bash +# Edit the compose file and change: +# - WEBUI_SECRET_KEY +# - N8N_BASIC_AUTH_PASSWORD +# - WEBHOOK_URL (use your server's IP) +# - GENERIC_TIMEZONE +nano ai-stack-compose.yml +``` + +4. **Start the stack**: +```bash +docker-compose -f ai-stack-compose.yml up -d +``` + +5. **Pull Ollama models**: +```bash +docker exec -it ollama ollama pull qwen2.5-coder:7b +docker exec -it ollama ollama pull llama3.2:3b +``` + +6. **Verify services**: +```bash +docker-compose -f ai-stack-compose.yml ps +``` + +## Configuration + +### Open WebUI Setup + +1. Navigate to `http://your-server-ip:3000` +2. Create your admin account (first user becomes admin) +3. Go to **Settings → Connections** and verify Ollama connection +4. Configure Qdrant: + - Host: `qdrant` + - Port: `6333` + +### Setting Up RAG for Wiki.js + +1. In Open WebUI, go to **Workspace → Knowledge** +2. Create a new collection: "Homelab Documentation" +3. Add sources: + - **URL Crawl**: Enter your Wiki.js base URL + - **File Upload**: Upload markdown files from repositories +4. Process and index the documents + +### n8n Initial Configuration + +1. Navigate to `http://your-server-ip:5678` +2. Log in with credentials from docker-compose file +3. Import starter workflows from `/n8n/workflows/` directory + +## Use Cases + +### 1. Automated Documentation Generation + +**Workflow**: Forgejo webhook → n8n → Ollama → Wiki.js + +When code is pushed to Forgejo: +1. n8n receives webhook from Forgejo +2. Extracts changed files and repo context +3. Sends to Ollama with prompt: "Generate documentation for this code" +4. Posts generated docs to Wiki.js via API + +**Example n8n Workflow**: +``` +Webhook Trigger + → HTTP Request (Forgejo API - get file contents) + → Ollama LLM Node (generate docs) + → HTTP Request (Wiki.js API - create/update page) + → Send notification (completion) +``` + +### 2. Docker-Compose Standardization + +**Workflow**: Repository scan → compliance check → issue creation + +1. n8n runs on schedule (daily/weekly) +2. Queries Forgejo API for all repositories +3. Scans for `docker-compose.yml` files +4. Compares against template standards stored in Qdrant +5. Generates compliance report with Ollama +6. Creates Forgejo issues for non-compliant repos + +### 3. Intelligent Alert Processing + +**Workflow**: Monitoring alert → AI analysis → smart routing + +1. Beszel/Uptime Kuma sends webhook to n8n +2. n8n queries historical data and context +3. Ollama analyzes: + - Is this expected? (scheduled backup, known maintenance) + - Severity level + - Recommended action +4. Routes appropriately: + - Critical: Immediate notification (Telegram/email) + - Warning: Log and monitor + - Info: Suppress (expected behavior) + +### 4. Email Monitoring & Triage + +**Workflow**: IMAP polling → AI classification → action routing + +1. n8n polls email inbox every 5 minutes +2. Filters for keywords: "alert", "critical", "down", "failed" +3. Ollama classifies urgency and determines if actionable +4. Routes based on classification: + - Urgent: Forward to you immediately + - Informational: Daily digest + - Spam: Archive + +## Common Workflows + +### Example: Repository Documentation Generator + +```javascript +// n8n workflow nodes: + +1. Schedule Trigger (daily at 2 AM) + ↓ +2. HTTP Request - Forgejo API + URL: http://forgejo:3000/api/v1/repos/search + Method: GET + ↓ +3. Loop Over Items (each repo) + ↓ +4. HTTP Request - Get repo files + URL: {{$node["Forgejo API"].json["clone_url"]}}/contents + ↓ +5. Filter - Find docker-compose.yml and README.md + ↓ +6. Ollama Node + Model: qwen2.5-coder:7b + Prompt: "Analyze this docker-compose file and generate comprehensive + documentation including: purpose, services, ports, volumes, + environment variables, and setup instructions." + ↓ +7. HTTP Request - Wiki.js API + URL: http://wikijs:3000/graphql + Method: POST + Body: {mutation: createPage(...)} + ↓ +8. Send Notification + Service: Telegram/Email + Message: "Documentation updated for {{repo_name}}" +``` + +### Example: Alert Intelligence Workflow + +```javascript +// n8n workflow nodes: + +1. Webhook Trigger + Path: /webhook/monitoring-alert + ↓ +2. Function Node - Parse Alert Data + JavaScript: Extract service, metric, value, timestamp + ↓ +3. HTTP Request - Query Historical Data + URL: http://beszel:8090/api/metrics/history + ↓ +4. Ollama Node + Model: llama3.2:3b + Context: Your knowledge base in Qdrant + Prompt: "Alert: {{alert_message}} + Historical context: {{historical_data}} + Is this expected behavior? + What's the severity? + What action should be taken?" + ↓ +5. Switch Node - Route by Severity + Conditions: + - Critical: Route to immediate notification + - Warning: Route to monitoring channel + - Info: Route to log only + ↓ +6a. Send Telegram (Critical path) +6b. Post to Slack (Warning path) +6c. Write to Log (Info path) +``` + +## Maintenance + +### Model Management + +```bash +# List installed models +docker exec -it ollama ollama list + +# Update a model +docker exec -it ollama ollama pull qwen2.5-coder:7b + +# Remove unused models +docker exec -it ollama ollama rm old-model:tag +``` + +### Backup Important Data + +```bash +# Backup Qdrant vector database +docker-compose -f ai-stack-compose.yml stop qdrant +tar -czf qdrant-backup-$(date +%Y%m%d).tar.gz ./qdrant_data/ +docker-compose -f ai-stack-compose.yml start qdrant + +# Backup n8n workflows (automatic to ./n8n/workflows) +tar -czf n8n-backup-$(date +%Y%m%d).tar.gz ./n8n_data/ + +# Backup Open WebUI data +tar -czf openwebui-backup-$(date +%Y%m%d).tar.gz ./open_webui_data/ +``` + +### Log Monitoring + +```bash +# View all stack logs +docker-compose -f ai-stack-compose.yml logs -f + +# View specific service +docker logs -f ollama +docker logs -f n8n +docker logs -f open-webui +``` + +### Resource Monitoring + +```bash +# Check resource usage +docker stats + +# Expected usage: +# - ollama: 4-6GB RAM (with model loaded) +# - open-webui: ~500MB RAM +# - qdrant: ~1GB RAM +# - n8n: ~200MB RAM +``` + +## Troubleshooting + +### Ollama Not Responding + +```bash +# Check if Ollama is running +docker logs ollama + +# Restart Ollama +docker restart ollama + +# Test Ollama API +curl http://localhost:11434/api/tags +``` + +### Open WebUI Can't Connect to Ollama + +1. Check network connectivity: +```bash +docker exec -it open-webui ping ollama +``` + +2. Verify Ollama URL in Open WebUI settings +3. Restart both containers: +```bash +docker restart ollama open-webui +``` + +### n8n Workflows Failing + +1. Check n8n logs: +```bash +docker logs n8n +``` + +2. Verify webhook URLs are accessible +3. Test Ollama connection from n8n: + - Create test workflow + - Add Ollama node + - Run execution + +### Qdrant Connection Issues + +```bash +# Check Qdrant health +curl http://localhost:6333/health + +# View Qdrant logs +docker logs qdrant + +# Restart if needed +docker restart qdrant +``` + +## Performance Optimization + +### Model Selection by Use Case + +- **Quick queries, chat**: `llama3.2:3b` or `phi3:mini` (fastest) +- **Code analysis**: `qwen2.5-coder:7b` or `deepseek-coder:6.7b` +- **Complex reasoning**: `mistral:7b` or `llama3.1:8b` + +### n8n Workflow Optimization + +- Use **Wait** nodes to batch operations +- Enable **Execute Once** for loops to reduce memory +- Store large data in temporary files instead of node output +- Use **Split In Batches** for processing large datasets + +### Qdrant Performance + +- Default settings are optimized for homelab use +- Increase `collection_shards` if indexing >100,000 documents +- Enable quantization for large collections + +## Security Considerations + +### Change Default Credentials + +```bash +# Generate secure password +openssl rand -base64 32 + +# Update in docker-compose.yml: +# - WEBUI_SECRET_KEY +# - N8N_BASIC_AUTH_PASSWORD +``` + +### Network Isolation + +Consider using a reverse proxy (Traefik, Nginx Proxy Manager) with authentication: +- Limit external access to Open WebUI only +- Keep n8n, Ollama, Qdrant on internal network +- Use VPN for remote access + +### API Security + +- Use strong API tokens for Wiki.js and Forgejo integrations +- Rotate credentials periodically +- Audit n8n workflow permissions + +## Integration Points + +### Connecting to Existing Services + +**Uptime Kuma**: +- Configure webhook alerts → n8n webhook URL +- Path: `http://your-server-ip:5678/webhook/uptime-kuma` + +**Beszel**: +- Use Shoutrrr webhook format +- URL: `http://your-server-ip:5678/webhook/beszel` + +**Forgejo**: +- Repository webhooks for push events +- URL: `http://your-server-ip:5678/webhook/forgejo-push` +- Enable in repo settings → Webhooks + +**Wiki.js**: +- GraphQL API endpoint: `http://wikijs:3000/graphql` +- Create API key in Wiki.js admin panel +- Store in n8n credentials + +## Advanced Features + +### Creating Custom n8n Nodes + +For frequently used Ollama prompts, create custom nodes: + +1. Go to n8n → Settings → Community Nodes +2. Install `n8n-nodes-ollama-advanced` if available +3. Or create Function nodes with reusable code + +### Training Custom Models + +While Ollama doesn't support fine-tuning directly, you can: +1. Use RAG with your specific documentation +2. Create detailed system prompts in n8n +3. Store organization-specific context in Qdrant + +### Multi-Agent Workflows + +Chain multiple Ollama calls for complex tasks: +``` +Planning Agent → Execution Agent → Review Agent → Output +``` + +Example: Code refactoring +1. Planning: Analyze code and create refactoring plan +2. Execution: Generate refactored code +3. Review: Check for errors and improvements +4. Output: Create pull request with changes + +## Resources + +- **Ollama Documentation**: https://ollama.ai/docs +- **Open WebUI Docs**: https://docs.openwebui.com +- **n8n Documentation**: https://docs.n8n.io +- **Qdrant Docs**: https://qdrant.tech/documentation + +## Support + +For issues or questions: +1. Check container logs first +2. Review this documentation +3. Search n8n community forums +4. Check Ollama Discord/GitHub issues + +--- + +**Last Updated**: {{current_date}} +**Maintained By**: Homelab Admin +**Status**: Production