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 # kuma
## Overview ## 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 ## Architecture
| Service | Image | Port | Role | | Service | Image | Port | Role |
|---------|-------|------|------| |---------|-----|-----|---------|
- **Host:** docker4 - **kuma:** docker4 3001 - monitoring service
- **Network:** netgrimoire - **autokuma:** docker4 3002 - automation service
- **Exposed via:** kuma:3001 (Caddy reverse proxy)
- **Homepage group:** Monitoring Exposed via:
- kuma: http://kuma.netgrimoire.com
- autokuma: Internal only, no external access expected
Homepage group: homepage group
--- ---
## Build & Configuration ## Build & Configuration
### Prerequisites ### Prerequisites
- The `docker` and `docker-compose` commands are required. No specific prerequisites for this stack.
### Volume Setup ### Volume Setup
```bash ```bash
mkdir -p /DockerVol/kuma mkdir -p /DockerVol/kuma:/app/data
chown -R docker4:kuma /DockerVol/kuma chown -R 1964:1964 /DockerVol/
``` ```
### Environment Variables ### Environment Variables
```bash - `AUTOKUMA__KUMA__URL`: http://kuma:3001
AUTOKUMA__KUMA__URL=http://kuma:3001 - `AUTOKUMA__KUMA__USERNAME`: traveler
AUTOKUMA__KUMA__USERNAME=traveler - `AUTOKUMA__KUMA__PASSWORD`: F@lcon12
AUTOKUMA__KUMA__PASSWORD=F@lcon12 - `AUTOKUMA__TAG_NAME`: AutoKuma
AUTOKUMA__TAG_NAME=AutoKuma - `AUTOKUMA__DOCKER__SOURCE`: DockerSwarm
AUTOKUMA__DOCKER__SOURCE="DockerSwarm"
AUTOKUMA__MIGRATE="true"
# generate: openssl rand -hex 32
```
### Deploy ### Deploy
```bash ```bash
@ -50,7 +48,16 @@ docker stack services kuma
``` ```
### First Run ### 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 ### Accessing kuma
| Service | URL | Purpose | | 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 ### 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 ### 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 ## Operations
### Monitoring ### Monitoring
Docker Stack services:
```bash ```bash
docker stack services kuma docker stack services kuma
docker service logs -f kuma docker service logs -f kuma
``` ```
### Backups ### Backups
- Critical: /DockerVol/kuma (automatically backed up by Docker Swarm) Critical data is stored in `/var/run/docker.sock:/var/run/docker.sock`.
- Reconstructable: No specific backup paths needed
### Restore ### Restore
```bash ```bash
cd services/swarm/stack/kuma cd /DockerVol/
./deploy.sh # 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 ## Common Failures
| Symptom | Cause | Fix | - **Symptom:** kuma service does not start.
|---------|-------|-----| - **Cause:** Autokuma service has incorrect configuration, Docker Swarm is not available on all nodes.
| 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. | - **Fix:** Check the autokuma service's configuration and ensure Docker Swarm is enabled on each node.
| AutoKuma not detecting new services | Misconfigured `AUTOKUMA__MIGRATE` environment variable | Set `AUTOKUMA__MIGRATE` to "true". | - **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 | | Date | Commit | Summary |
|------|--------|---------| |------|--------|---------|
| 2026-04-06 | 42982c9a | Initial documentation. | | 2026-04-07 | d6fffdfb | Initial documentation |
| 2026-04-06 | 9d8b36be | Improved `AUTOKUMA__MIGRATE` configuration. | | 2026-04-06 | 42982c9a | Initial commit |
| 2026-04-06 | 3f791e83 | Added `docker-compose` support. | | 2026-04-06 | 9d8b36be | Initial commit |
| 2026-04-04 | 5b03dbf9 | Simplified `deploy.sh`. | | 2026-04-06 | 3f791e83 | Initial commit |
| 2026-04-04 | 6f0000c4 | Improved error handling for `kuma` service. | | 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.> <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 ## 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 - Source: swarm/kuma.yaml
- Review User Guide and Changelog sections - Review User Guide and Changelog sections