traveler/Netgrimoire
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

New Grimoire

Browse source
This commit is contained in:
traveler 2026-04-12 09:53:51 -05:00
parent 77d589a13d
commit cc574f8aed
157 changed files with 29420 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

72
Gremlin-Grimoire/Overview.md Normal file
View file

@ -0,0 +1,72 @@
---
title: Gremlin Grimoire
description: Netgrimoire's local AI — the gremlin that runs the machine
published: true
date: 2026-04-12T00:00:00.000Z
tags: gremlin, ai, ollama, n8n
editor: markdown
dateCreated: 2026-04-12T00:00:00.000Z
---
# Gremlin Grimoire
![gremlin-badge](/images/gremlin-badge.png)
Gremlin is the local AI layer of Netgrimoire. It's not just a chat interface — it's an autonomous agent that watches the infrastructure, audits the codebase, triages alerts, and answers questions about the lab. The gremlin lives inside the machine and knows every dark corner of it.
---
## What Gremlin Is
Gremlin is a stack of four services running together on `docker4`, all pinned to the same Swarm node:
| Service | Role | URL |
|---------|------|-----|
| **Ollama** | Local LLM inference (CPU-only, Ryzen) | `http://ollama:11434` · `ollama.netgrimoire.com:11434` |
| **Open WebUI** | Chat interface + RAG frontend | `https://ai.netgrimoire.com` |
| **Qdrant** | Vector database for RAG knowledge base | `http://qdrant:6333` · dashboard `:6333/dashboard` |
| **n8n** | Automation brain — autonomous workflows | `https://n8n.netgrimoire.com` |
---
## What Gremlin Does Today
| Capability | Status | Workflow |
|-----------|--------|---------|
| Weekly YAML audit of all compose files | ✅ Live | Forgejo Audit — Monday 06:00 |
| Uptime Kuma alert triage | ✅ Live | Kuma Triage — webhook-triggered |
| Interactive chat with lab context | ✅ Live | Open WebUI + Ollama |
| RAG over wiki/docs | 🔧 Wired, not populated | Qdrant connected, knowledge base empty |
| Doc generation from compose files | 🟡 Parked | CPU quality insufficient — awaiting GPU |
| Email triage | 📋 Planned | Phase 3 — not built |
---
## Models
| Model | Size | Used For |
|-------|------|---------|
| `qwen2.5-coder:7b` | ~5 GB | Code review, YAML audits, compose analysis |
| `llama3.2:3b` | ~2 GB | Alert triage, Q&A, summarization |
Models must be pulled before workflows run. See [Ollama Model Management](/Gremlin-Grimoire/Runbooks/Model-Management).
---
## Sections
| | |
|---|---|
| [Stack](/Gremlin-Grimoire/Stack/Build-Config) | Full build config, volumes, env vars, compose YAML |
| [Workflows](/Gremlin-Grimoire/Workflows/Forgejo-Audit) | All n8n workflows — architecture, patterns, gotchas |
| [Runbooks](/Gremlin-Grimoire/Runbooks/Deploy) | Deploy, model management, troubleshooting |
---
## Planned Evolution
- **Homelable MCP backend** — next up. Provides tool-use for infra Q&A (topology, running services, resource usage). Blocked until Homelable stack is deployed.
- **GPU support** — unlocks doc generation and larger models. Compose GPU block is commented out, ready to enable.
- **Gremlin role variants** — specialized personas per domain (Proxy Gremlin, Storage Gremlin, Security Gremlin, etc.) with mood states and dynamic badge serving via Caddy.
- **RAG knowledge base population** — index all Wiki.js pages and the compose template standard into Qdrant.
- **Gremlin Router** — dedicated Flask container for webhook routing (currently handled directly by n8n).

73
Gremlin-Grimoire/Runbooks/Deploy.md Normal file
View file

@ -0,0 +1,73 @@
---
title: Deploy Gremlin Stack
description: How to deploy and redeploy the Gremlin AI stack
published: true
date: 2026-04-12T00:00:00.000Z
tags: gremlin, deploy, runbook
editor: markdown
dateCreated: 2026-04-12T00:00:00.000Z
---
# Deploy Gremlin Stack
All Gremlin services run on `docker4` (hermes), pinned via `node.hostname == docker4`.
---
## Prerequisites
```bash
# On docker4 — create volume directories
mkdir -p /DockerVol/ollama
mkdir -p /DockerVol/open-webui
mkdir -p /DockerVol/qdrant
# n8n requires specific ownership
mkdir -p /DockerVol/n8n
chown -R 1000:1000 /DockerVol/n8n
```
---
## Deploy
```bash
cd ~/services && git pull
cd swarm/stack/Gremlin
set -a && source .env && set +a
docker stack config --compose-file gremlin-stack.yml > resolved.yml
docker stack deploy --compose-file resolved.yml gremlin
rm resolved.yml
docker stack services gremlin
```
---
## Pull Models After Deploy
Models must be pulled before n8n workflows run. Ollama returns a silent model-not-found error if workflows fire first.
```bash
docker exec $(docker ps -qf name=gremlin_ollama) ollama pull llama3.2:3b
docker exec $(docker ps -qf name=gremlin_ollama) ollama pull qwen2.5-coder:7b
# Verify
docker exec $(docker ps -qf name=gremlin_ollama) ollama list
```
---
## Verify Open WebUI Secret Key
Check that `WEBUI_SECRET_KEY` in `.env` on docker4 is set to a real secret, not the placeholder `change-this-secret-key`.
---
## Service URLs After Deploy
| Service | Internal | External |
|---------|----------|---------|
| Ollama | `http://ollama:11434` | `http://ollama.netgrimoire.com:11434` |
| Open WebUI | `http://open-webui:8080` | `https://ai.netgrimoire.com` |
| Qdrant | `http://qdrant:6333` | `http://qdrant.netgrimoire.com:6333/dashboard` |
| n8n | `http://n8n:5678` | `https://n8n.netgrimoire.com` |

41
Gremlin-Grimoire/Runbooks/Model-Management.md Normal file
View file

@ -0,0 +1,41 @@
---
title: Ollama Model Management
description: Pulling, verifying, and managing models on the Gremlin stack
published: true
date: 2026-04-12T00:00:00.000Z
tags: gremlin, ollama, models, runbook
editor: markdown
dateCreated: 2026-04-12T00:00:00.000Z
---
# Ollama Model Management
## Pull Required Models
Run on docker4 after any fresh deploy or after the Ollama container is recreated:
```bash
docker exec $(docker ps -qf name=gremlin_ollama) ollama pull llama3.2:3b
docker exec $(docker ps -qf name=gremlin_ollama) ollama pull qwen2.5-coder:7b
```
## Verify Models Loaded
```bash
docker exec $(docker ps -qf name=gremlin_ollama) ollama list
```
## Model Reference
| Model | Size | Pull Time (CPU) | Used By |
|-------|------|----------------|---------|
| `llama3.2:3b` | ~2 GB | ~5 min | Kuma triage, Open WebUI |
| `qwen2.5-coder:7b` | ~5 GB | ~15 min | Forgejo audit, Open WebUI |
## Models Storage Path
`/DockerVol/ollama` — survives container restarts and redeployments.
## ⚠ Pull Before Workflows Run
n8n workflows fail silently if models aren't present. Ollama returns a model-not-found response but n8n may not surface this as an obvious error. Always pull models immediately after deploy before enabling workflows.

64
Gremlin-Grimoire/Runbooks/Troubleshooting.md Normal file
View file

@ -0,0 +1,64 @@
---
title: Gremlin Troubleshooting
description: Common Gremlin stack problems and fixes
published: true
date: 2026-04-12T00:00:00.000Z
tags: gremlin, troubleshooting, runbook
editor: markdown
dateCreated: 2026-04-12T00:00:00.000Z
---
# Gremlin Troubleshooting
## n8n Won't Start / Permission Error
```bash
# On docker4
chown -R 1000:1000 /DockerVol/n8n
docker service update --force gremlin_n8n
```
## Workflow Fails Silently on Ollama Call
Model not pulled. Ollama returns model-not-found but n8n may not surface it clearly.
```bash
docker exec $(docker ps -qf name=gremlin_ollama) ollama list
# If model missing:
docker exec $(docker ps -qf name=gremlin_ollama) ollama pull llama3.2:3b
docker exec $(docker ps -qf name=gremlin_ollama) ollama pull qwen2.5-coder:7b
```
## Forgejo Webhook Not Reaching n8n
Add to Forgejo `app.ini`:
```ini
[webhook]
ALLOWED_HOST_LIST = *
```
Restart Forgejo. Required when `OFFLINE_MODE = true`.
## Caddy Routes to Wrong Container IP
Ensure all Gremlin services include in labels:
```yaml
caddy_ingress_network: netgrimoire
```
Never use `{{upstreams PORT}}` — breaks during `docker stack config` preprocessing. Use `caddy.reverse_proxy: servicename:PORT`.
## Audit Workflow Times Out
Check `N8N_RUNNERS_TASK_TIMEOUT` is set to `3600` in n8n environment. Default timeout is too short for 67-file audit runs.
## n8n Code Node Can't Access Env Vars
Set `N8N_BLOCK_ENV_ACCESS_IN_NODE=false` in n8n environment.
## Open WebUI Can't Connect to Qdrant
Verify both services are on the `netgrimoire` overlay and pinned to `docker4`. Qdrant gRPC port is 6334, REST is 6333.
## Audit Reports Not Committing to Forgejo
Check write token is set in n8n credentials. The read and write tokens are separate — confirm the workflow is using the write token for commit operations (POST new files, PUT+SHA for updates).

503
Gremlin-Grimoire/Stack/Agent-Docs.md Normal file
View file

@ -0,0 +1,503 @@
---
title: Ollama with agent
description: The smart home reference
published: true
date: 2026-04-02T21:11:09.564Z
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

383
Gremlin-Grimoire/Stack/Build-Config.md Normal file
View file

File diff suppressed because one or more lines are too long

194
Gremlin-Grimoire/Stack/User-Guide.md Normal file
View file

File diff suppressed because one or more lines are too long

105
Gremlin-Grimoire/Workflows/Forgejo-Audit.md Normal file
View file

@ -0,0 +1,105 @@
---
title: Forgejo Audit Workflow
description: Weekly automated YAML compliance audit via n8n + Ollama
published: true
date: 2026-04-12T00:00:00.000Z
tags: gremlin, n8n, audit, forgejo
editor: markdown
dateCreated: 2026-04-12T00:00:00.000Z
---
# Forgejo Audit Workflow
**Status:** ✅ Live and confirmed working
Runs every Monday at 06:00. Walks all compose YAML files in `services/swarm/` and `services/swarm/stack/*/`, audits each one against the Swarm template standard using `qwen2.5-coder:7b`, and commits full reports to Forgejo + sends a summary to ntfy.
---
## What It Audits
Each file is checked for:
- Homepage labels on all services
- Uptime Kuma labels on all services
- Caddy labels on exposed services
- `node.platform.arch` exclusion constraints (ARM default)
- Volume paths follow `/DockerVol/` or `/data/nfs/znas/Docker/` convention
- No forbidden fields (`version:`, `container_name:`, `restart:`, `depends_on:`)
- `endpoint_mode: dnsrr` not used
- `diun.enable: "true"` present
- Network references `netgrimoire` external overlay
---
## Scope
~67 files total across `swarm/` (flat single-service YAMLs) and `swarm/stack/*/` (grouped stacks).
---
## Outputs
| Output | Where | Content |
|--------|-------|---------|
| ntfy notification | `gremlin-audits` topic | Short FAIL summary per file |
| Forgejo commit | `Netgrimoire/Audits/AUDIT-<name>-<date>.md` | Full audit report (POST new / PUT+SHA update) |
---
## n8n Architecture
```
Schedule Trigger (Mon 06:00)
→ Forgejo API: list all files in swarm/ and swarm/stack/*/
→ Loop Over Items (splitInBatches, batch=1)
→ Code node: fetch file content via Forgejo API
→ Code node: build Ollama prompt
→ Code node: POST to Ollama (qwen2.5-coder:7b)
→ Code node: parse result, build report markdown
→ Code node: commit report to Forgejo (POST or PUT+SHA)
→ Code node: send ntfy summary if FAIL
→ Loop feedback connection drives iteration
```
---
## Critical Patterns
All Forgejo and Ollama API calls use `this.helpers.httpRequest()` in Code nodes — **not** HTTP Request nodes. HTTP Request nodes hit body expression limits on large prompts.
Code nodes in "Run Once for Each Item" mode must return `{ json: ... }` not `[{ json: ... }]`.
Loop Over Items (splitInBatches, batch=1) + feedback connection from last node back to loop drives iteration over multiple files.
---
## Critical Environment Variables
| Variable | Value | Why |
|----------|-------|-----|
| `N8N_BLOCK_ENV_ACCESS_IN_NODE` | `false` | Allows env var access inside Code nodes |
| `N8N_RUNNERS_TASK_TIMEOUT` | `3600` | Prevents timeout on 67-file audit runs |
---
## Forgejo API Tokens
| Token | Scope |
|-------|-------|
| Read token | Fetch file content from `traveler/services` |
| Write token | Commit audit reports to `traveler/Netgrimoire` |
Tokens stored in n8n credentials, not in compose env vars.
---
## Forgejo Webhook Gotcha
If Forgejo webhooks fail to reach n8n, add to Forgejo `app.ini`:
```ini
[webhook]
ALLOWED_HOST_LIST = *
```
Required when `OFFLINE_MODE = true`. Restart Forgejo after edit.

63
Gremlin-Grimoire/Workflows/Kuma-Triage.md Normal file
View file

@ -0,0 +1,63 @@
---
title: Kuma Alert Triage Workflow
description: Uptime Kuma webhook → Ollama analysis → ntfy alert
published: true
date: 2026-04-12T00:00:00.000Z
tags: gremlin, n8n, kuma, alerts
editor: markdown
dateCreated: 2026-04-12T00:00:00.000Z
---
# Kuma Alert Triage Workflow
**Status:** ✅ Live and confirmed working
Triggered by Uptime Kuma webhook on service DOWN or RECOVERED events. DOWN events are analyzed by `llama3.2:3b` before alerting. RECOVERED events skip AI and send a simple notification.
---
## Webhook URL
```
https://n8n.netgrimoire.com/webhook/gremlin-kuma-alert
```
Configure in Uptime Kuma: Settings → Notifications → Webhook → apply to all monitors.
---
## Flow
```
Kuma Webhook
├── DOWN path:
│ → Parse payload (service name, URL, error)
│ → Ollama (llama3.2:3b): triage prompt
│ → ntfy gremlin-alerts (urgent priority) with AI analysis
│
└── RECOVERED path:
→ ntfy gremlin-alerts (normal priority, no AI call)
```
---
## Why Two Paths
AI triage is only useful for DOWN events — there's nothing to analyze on a recovery. Skipping Ollama on RECOVERED keeps notification latency near-instant for good news.
---
## ntfy Output Format
DOWN alert includes:
- Service name and URL
- Kuma error message
- Ollama's triage assessment (probable cause, suggested first step)
RECOVERED alert is a simple one-liner.
---
## Parked: Doc Generation Workflows
Two additional doc generation workflows were built but are currently inactive. CPU-only `llama3.2:3b` output barely exceeds reformatting the source compose file — not useful enough to commit. Will be revisited when GPU support is added to the Gremlin stack.