docs: create netgrimoire-agent
This commit is contained in:
Administrator
John Smith
parent
de786b5b48
commit
5197c9be71
1 changed files with 503 additions and 0 deletions
503
netgrimoire-agent.md
Normal file
503
netgrimoire-agent.md
Normal file
|
|
@ -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
|
||||
Loading…
Add table
Add a link
Reference in a new issue