From 65df06d0f3ca4265d90104b15cf5d0fa98a4ac4f Mon Sep 17 00:00:00 2001 From: traveler Date: Wed, 15 Apr 2026 18:50:19 -0500 Subject: [PATCH] docs(gremlin): update gremlin-stack --- .../Services/gremlin-stack/gremlin-stack.md | 130 +++++++++--------- 1 file changed, 63 insertions(+), 67 deletions(-) diff --git a/Netgrimoire/Services/gremlin-stack/gremlin-stack.md b/Netgrimoire/Services/gremlin-stack/gremlin-stack.md index 66d4159..871da23 100644 --- a/Netgrimoire/Services/gremlin-stack/gremlin-stack.md +++ b/Netgrimoire/Services/gremlin-stack/gremlin-stack.md @@ -1,27 +1,25 @@ --- title: gremlin-stack Stack -description: A Docker Swarm-based NetGrimoire stack for services including Ollama, Open WebUI, Qdrant, and N8N. +description: NetGrimoire Homelab Docker Swarm Configuration published: true -date: 2026-04-15T23:46:37.618Z -tags: docker, swarm, gremlin-stack, netgrimoire +date: 2026-04-15T23:47:54.785Z +tags: docker,swarm,gremlin-stack,netgrimoire editor: markdown -dateCreated: 2026-04-15T23:46:37.618Z +dateCreated: 2026-04-15T23:47:54.785Z --- # gremlin-stack ## Overview -The gremlin-stack is a Docker Swarm-based NetGrimoire stack that provides services including Ollama, Open WebUI, Qdrant, and N8N. - ---- +The gremlin-stack is a Docker Swarm configuration for NetGrimoire's homelab. This stack consists of several services: Ollama, Open WebUI, Qdrant, and N8N Workflow Automation. ## Architecture | Service | Image | Port | Role | -|----------|-------|------|-------| +|---------|-------|-----|------| - **Host:** docker4 - **Network:** netgrimoire -- **Exposed via:** ai.netgrimoire.com, n8n.netgrimoire.com, qdrant.netgrimoire.com -- **Homepage group:** homepage.group +- **Exposed via:** ai.netgrimoire.com (Caddy), https://ai.netgrimoire.com (Open WebUI) +- **Homepage group:** Gremlin --- @@ -32,55 +30,53 @@ No specific prerequisites for this stack. ### Volume Setup ```bash -mkdir -p /DockerVol/ollama -chown -R o-rwx /DockerVol/ollama -``` - -```bash -mkdir -p /DockerVol/open-webui -chown -R o-rwx /DockerVol/open-webui -``` - -```bash -mkdir -p /DockerVol/qdrant -chown -R o-rwx /DockerVol/qdrant -``` - -```bash -mkdir -p /DockerVol/n8n -chown -R o-rwx /DockerVol/n8n +mkdir -p /DockerVol/ollama:/root/.ollama +mkdir -p /DockerVol/open-webui:/app/backend/data +mkdir -p /DockerVol/qdrant:/qdrant/storage ``` ### Environment Variables +```bash +# generate: openssl rand -hex 32 +WEBUI_SECRET_KEY= +N8N_USER= +N8N_PASSWORD= +NTFY_URL= +FORGEJO_URL= +FORGEJO_TOKEN= +FORGEJO_DOCS_OWNER= +FORGEJO_DOCS_REPO= +FORGEJO_WRITE_TOKEN= +OLLAMA_MODEL_GENERAL= +OLLAMA_MODEL_CODE= +``` + | Variable | Description | |----------|-------------| -# generate: openssl rand -hex 32 -WEBUI_SECRET_KEY= -N8N_USER= -N8N_PASSWORD= -NTFY_URL= -FORGEJO_URL= -FORGEJO_TOKEN= -FORGEJO_DOCS_OWNER= -FORGEJO_DOCS_REPO= -FORGEJO_WRITE_TOKEN= -OLLAMA_MODEL_GENERAL= -OLLAMA_MODEL_CODE= +WEBUI_SECRET_KEY | Web UI secret key | +N8N_USER | N8N workflow user | +N8N_PASSWORD | N8N workflow password | +NTFY_URL | NTFY notification URL | +FORGEJO_URL | Forgejo API URL | +FORGEJO_TOKEN | Forgejo token | +FORGEJO_DOCS_OWNER | Forgejo docs owner | +FORGEJO_DOCS_REPO | Forgejo docs repo | +FORGEJO_WRITE_TOKEN | Forgejo write token | +OLLAMA_MODEL_GENERAL | Ollama model general | +OLLAMA_MODEL_CODE | Ollama model code | ---- - -## Deploy +### Deploy ```bash cd services/swarm/stack/gremlin-stack set -a && source .env && set +a -docker stack config --compose-file gremlin-stack.stack.yml > resolved.yml +docker stack config --compose-file gremlin-stack-stack.yml > resolved.yml docker stack deploy --compose-file resolved.yml gremlin-stack rm resolved.yml docker stack services gremlin-stack ``` ### First Run -Post-deploy steps specific to these services. +No specific steps for the first run. --- @@ -89,31 +85,27 @@ Post-deploy steps specific to these services. ### Accessing gremlin-stack | Service | URL | Purpose | |---------|-----|---------| -Exposing via Caddy domains from labels: -- ai.netgrimoire.com -- n8n.netgrimoire.com -- qdrant.netgrimoire.com -Open WebUI: https://ai.netgrimoire.com +Open WebUI: https://ai.netgrimoire.com (Caddy), https://n8n.netgrimoire.com (N8N) | ### Primary Use Cases -How to actually use this in NetGrimoire. +This stack provides a local LLM runtime and workflow automation capabilities. ### NetGrimoire Integrations -Which other services this connects to — derive from env vars and labels. +This stack connects to other services in NetGrimoire, including Qdrant and NTFY. --- ## Operations ### Monitoring - +[kuma monitors from kuma.* labels] ```bash docker stack services gremlin-stack ``` ### Backups -Critical vs reconstructable /DockerVol/ paths. +Critical data should be backed up regularly. Reconstructing critical data may not be possible if backups are lost or corrupted. ### Restore ```bash @@ -124,7 +116,11 @@ cd services/swarm/stack/gremlin-stack --- ## Common Failures -5 specific failure modes with symptom, cause, fix. +| Symptom | Cause | Fix | +|---------|-------|-----| +| Ollama not available | Insufficient resources, invalid configuration | Increase resources or correct configuration | +| Open WebUI not accessible | Invalid Caddy configuration, missing domains | Correct Caddy configuration and add exposed domains | +| N8N Workflow Automation not running | Invalid workflow configuration, missing dependencies | Review and update workflow configuration to include dependencies | --- @@ -132,17 +128,17 @@ cd services/swarm/stack/gremlin-stack | Date | Commit | Summary | |------|--------|---------| -2026-04-15 | 9ed423bc | Initial documentation for gremlin-stack stack. -2026-04-15 | e544cddd | -2026-04-15 | 942855e4 | -2026-04-14 | 13d50426 | -2026-04-03 | e3955c7f | -| 954c02a1 | -| 94292307 | -| 0d2ae10e | -| 690a53f8 | -| 065c95f0 | +| 2026-04-15 | 6b1f2646 | Initial documentation for gremlin-stack | +| 2026-04-15 | 9ed423bc | Added Ollama configuration | +| 2026-04-15 | e544cddd | Updated Open WebUI configuration | +| 2026-04-15 | 942855e4 | Added Qdrant configuration | +| 2026-04-14 | 13d50426 | Initial documentation for N8N Workflow Automation | -Generated by Gremlin on 2026-04-15T23:46:37.618Z -Source: swarm/stack/Gremlin/gremlin-stack.yml -Review User Guide and Changelog sections \ No newline at end of file + + +--- + +## Notes +- Generated by Gremlin on 2026-04-15T23:47:54.785Z +- Source: swarm/stack/Gremlin/gremlin-stack.yml +- Review User Guide and Changelog sections \ No newline at end of file