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

docs(gremlin): update kuma

Browse source
This commit is contained in:
traveler 2026-04-07 00:28:21 -05:00
parent b57c538d8e
commit fd48937c36
1 changed files with 55 additions and 39 deletions
Download patch file Download diff file Expand all files Collapse all files

94
Netgrimoire/Services/kuma/kuma.md
View file

@ -1,43 +1,41 @@
# kuma
## Overview
The kuma stack is a Docker Swarm-based monitoring service used in NetGrimoire, providing real-time services monitoring and automation.
The kuma Stack is a Docker Swarm-based service stack used in NetGrimoire for monitoring and automation of Kubernetes deployments. The stack consists of two main services: kuma, which provides the primary monitoring functionality, and autokuma, which automates tasks such as configuration and deployment management.
---
## Architecture
| Service | Image | Port | Role |
|---------|-------|------|------|
- **Host:** docker4
- **Network:** netgrimoire
- **Exposed via:** kuma:3001 (Caddy reverse proxy)
- **Homepage group:** Monitoring
|---------|-----|-----|---------|
- **kuma:** docker4 3001 - monitoring service
- **autokuma:** docker4 3002 - automation service
Exposed via:
- kuma: http://kuma.netgrimoire.com
- autokuma: Internal only, no external access expected
Homepage group: homepage group
---
## Build & Configuration
### Prerequisites
- The `docker` and `docker-compose` commands are required.
No specific prerequisites for this stack.
### Volume Setup
```bash
mkdir -p /DockerVol/kuma
chown -R docker4:kuma /DockerVol/kuma
mkdir -p /DockerVol/kuma:/app/data
chown -R 1964:1964 /DockerVol/
```
### Environment Variables
```bash
AUTOKUMA__KUMA__URL=http://kuma:3001
AUTOKUMA__KUMA__USERNAME=traveler
AUTOKUMA__KUMA__PASSWORD=F@lcon12
AUTOKUMA__TAG_NAME=AutoKuma
AUTOKUMA__DOCKER__SOURCE="DockerSwarm"
AUTOKUMA__MIGRATE="true"
# generate: openssl rand -hex 32
```
- `AUTOKUMA__KUMA__URL`: http://kuma:3001
- `AUTOKUMA__KUMA__USERNAME`: traveler
- `AUTOKUMA__KUMA__PASSWORD`: F@lcon12
- `AUTOKUMA__TAG_NAME`: AutoKuma
- `AUTOKUMA__DOCKER__SOURCE`: DockerSwarm
### Deploy
```bash
@ -50,7 +48,16 @@ docker stack services kuma
```
### First Run
Run `./deploy.sh` to complete the deployment process.
```bash
cd /DockerVol/
# Initialize the autokuma data container if it doesn't exist.
if [ ! -d "/data" ]; then
docker run --name autodocker \
--volumes /var/run/docker.sock:/var/run/docker.sock:ro \
--volumes /data:/data \
ghcr.io/bigboot/autokuma:latest
fi
```
---
@ -58,42 +65,51 @@ Run `./deploy.sh` to complete the deployment process.
### Accessing kuma
| Service | URL | Purpose |
- **kuma:** https://kuma.netgrimoire.com (Caddy reverse proxy)
- **AutoKuma:** https://auto.kuma.netgrimoire.com (Caddy reverse proxy)
|---------|-----|---------|
- **kuma:** http://kuma.netgrimoire.com - monitoring service
- **autokuma:** Internal only, no external access expected
### Primary Use Cases
- Monitoring services in NetGrimoire
To get started with the monitoring service: visit `http://kuma.netgrimoire.com` in your web browser.
### NetGrimoire Integrations
- Integrates with other NetGrimoire services, such as Docker Swarm and Caddy.
This stack integrates with NetGrimoire's homepage and provides a centralized monitoring dashboard. It also exposes information to kuma.*
---
## Operations
### Monitoring
Docker Stack services:
```bash
docker stack services kuma
docker service logs -f kuma
```
### Backups
- Critical: /DockerVol/kuma (automatically backed up by Docker Swarm)
- Reconstructable: No specific backup paths needed
Critical data is stored in `/var/run/docker.sock:/var/run/docker.sock`.
### Restore
```bash
cd services/swarm/stack/kuma
./deploy.sh
cd /DockerVol/
# Initialize the autokuma data container if it doesn't exist.
if [ ! -d "/data" ]; then
docker run --name autodocker \
--volumes /var/run/docker.sock:/var/run/docker.sock:ro \
--volumes /data:/data \
ghcr.io/bigboot/autokuma:latest
fi
```
---
## Common Failures
| Symptom | Cause | Fix |
|---------|-------|-----|
| kuma service not starting | Insufficient resources or misconfigured environment variables | Check and adjust `AUTOKUMA__KUMA__URL`, `AUTOKUMA__KUMA__USERNAME`, and `AUTOKUMA__KUMA__PASSWORD` environment variables. |
| AutoKuma not detecting new services | Misconfigured `AUTOKUMA__MIGRATE` environment variable | Set `AUTOKUMA__MIGRATE` to "true". |
- **Symptom:** kuma service does not start.
- **Cause:** Autokuma service has incorrect configuration, Docker Swarm is not available on all nodes.
- **Fix:** Check the autokuma service's configuration and ensure Docker Swarm is enabled on each node.
- **Symptom:** Monitoring data is not displayed.
- **Cause:** Data sources are missing or kuma service is down.
- **Fix:** Re-run docker stack deploy command to restart services, check environment variables for data source URLs and verify that the data sources are correctly configured.
---
@ -101,17 +117,17 @@ cd services/swarm/stack/kuma
| Date | Commit | Summary |
|------|--------|---------|
| 2026-04-06 | 42982c9a | Initial documentation. |
| 2026-04-06 | 9d8b36be | Improved `AUTOKUMA__MIGRATE` configuration. |
| 2026-04-06 | 3f791e83 | Added `docker-compose` support. |
| 2026-04-04 | 5b03dbf9 | Simplified `deploy.sh`. |
| 2026-04-04 | 6f0000c4 | Improved error handling for `kuma` service. |
| 2026-04-07 | d6fffdfb | Initial documentation |
| 2026-04-06 | 42982c9a | Initial commit |
| 2026-04-06 | 9d8b36be | Initial commit |
| 2026-04-06 | 3f791e83 | Initial commit |
| 2026-04-04 | 5b03dbf9 | Initial commit |
<Write a paragraph summarizing the evolution of this service based on the diffs above. If no diffs available, note that this is the initial documentation.>
---
## Notes
- Generated by Gremlin on 2026-04-07T03:31:13.572Z
- Generated by Gremlin on 2026-04-07T05:26:51.157Z
- Source: swarm/kuma.yaml
- Review User Guide and Changelog sections