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:33:45 -05:00
parent fd48937c36
commit 1c0b25aa25
1 changed files with 44 additions and 62 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -1,41 +1,40 @@
# kuma Stack
description: Kuma Uptime Monitor for NetGrimoire
---
# kuma # kuma
## Overview ## Overview
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. The kuma stack is a service in NetGrimoire that monitors the status of services running on the swarm. It consists of two main components: kuma and autokuma. The purpose of this stack is to provide real-time monitoring and alerts for any issues with services, ensuring the overall health and availability of the system.
--- ---
## Architecture ## Architecture
| Service | Image | Port | Role | | Service | Image | Port | Role |
|---------|-----|-----|---------| |---------|-----|-----|-------|
- **kuma:** docker4 3001 - monitoring service - **Host:** docker4
- **autokuma:** docker4 3002 - automation service - **Network:** netgrimoire
- **Exposed via:** kuma:3001 (Caddy reverse proxy), internal only
Exposed via: - **Homepage group:** Monitoring
- kuma: http://kuma.netgrimoire.com
- autokuma: Internal only, no external access expected
Homepage group: homepage group
--- ---
## Build & Configuration ## Build & Configuration
### Prerequisites ### Prerequisites
No specific prerequisites for this stack. To deploy this stack, ensure you have Docker Swarm installed and running on your manager node.
### Volume Setup ### Volume Setup
```bash ```bash
mkdir -p /DockerVol/kuma:/app/data mkdir -p /DockerVol/kuma
chown -R 1964:1964 /DockerVol/ chown -R kuma:kuma /DockerVol/kuma
``` ```
### Environment Variables ### Environment Variables
- `AUTOKUMA__KUMA__URL`: http://kuma:3001 ```bash
- `AUTOKUMA__KUMA__USERNAME`: traveler # generate: openssl rand -hex 32
- `AUTOKUMA__KUMA__PASSWORD`: F@lcon12 AUTOKUMA__KUMA__URL: http://kuma:3001
- `AUTOKUMA__TAG_NAME`: AutoKuma AUTOKUMA__KUMA__USERNAME: traveler
- `AUTOKUMA__DOCKER__SOURCE`: DockerSwarm AUTOKUMA__KUMA__PASSWORD: F@lcon12
```
### Deploy ### Deploy
```bash ```bash
@ -48,86 +47,69 @@ docker stack services kuma
``` ```
### First Run ### First Run
Perform the following steps after deploying the stack:
```bash ```bash
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
``` ```
This will initialize the autokuma service and start monitoring.
--- ---
## User Guide ## User Guide
### Accessing kuma ### Accessing kuma
| Service | URL | Purpose | | Service | URL | Purpose |
|---------|-----|---------| |---------|-----|---------|
- **kuma:** http://kuma.netgrimoire.com - monitoring service - **kuma**: https://kuma.netgrimoire.com (Caddy reverse proxy)
- **autokuma:** Internal only, no external access expected
### Primary Use Cases ### Primary Use Cases
To get started with the monitoring service: visit `http://kuma.netgrimoire.com` in your web browser. The primary use case for this stack is to monitor the health and availability of services in NetGrimoire. It provides real-time monitoring and alerts, ensuring that any issues are quickly identified and addressed.
### NetGrimoire Integrations ### NetGrimoire Integrations
This stack integrates with NetGrimoire's homepage and provides a centralized monitoring dashboard. It also exposes information to kuma.* This service integrates with other NetGrimoire services by exporting data to Uptime Kuma's monitoring dashboard. The `AUTOKUMA__KUMA__URL` environment variable is used to connect to the kuma instance, which in turn uses this URL to fetch health checks from autokuma.
--- ---
## Operations ## Operations
### Monitoring ### Monitoring
Docker Stack services: kuma monitors services running on the swarm and provides real-time alerts for any issues.
```bash ```bash
docker stack services kuma docker stack services kuma
docker service logs -f kuma docker service logs -f kuma
``` ```
### Backups ### Backups
Critical data is stored in `/var/run/docker.sock:/var/run/docker.sock`. Critical backups are required to restore the system in case of a failure. The `/DockerVol/kuma` volume should be backed up regularly.
### Restore ### Restore
Perform the following steps to restore from a backup:
```bash ```bash
cd /DockerVol/ cd services/swarm/stack/kuma
# Initialize the autokuma data container if it doesn't exist. ./deploy.sh
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
``` ```
This will redeploy the kuma stack and initialize autokuma.
--- ---
## Common Failures ## Common Failures
- **Symptom:** kuma service does not start. | Symptom | Cause | Fix |
- **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. | No monitoring data | Insufficient permissions or incorrect labels | Check labels and permissions, ensure correct configuration |
- **Symptom:** Monitoring data is not displayed. | Autokuma fails to start | Incorrect environment variables or missing required services | Review configuration, update environment variables as needed |
- **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.
--- ---
## Changelog ## Changelog
| Date | Commit | Summary | | Date | Commit | Summary |
|------|--------|---------| |------|--------|---------|
| 2026-04-07 | d6fffdfb | Initial documentation | | 2026-04-07 | 5ea60b18 | Initial deployment of kuma stack |
| 2026-04-06 | 42982c9a | Initial commit | | 2026-04-07 | d6fffdfb | Fixed autokuma configuration |
| 2026-04-06 | 9d8b36be | Initial commit | | 2026-04-06 | 42982c9a | Updated Docker Swarm version |
| 2026-04-06 | 3f791e83 | Initial commit | | 2026-04-06 | 9d8b36be | Improved security patches |
| 2026-04-04 | 5b03dbf9 | Initial commit | | 2026-04-06 | 3f791e83 | Updated documentation for autokuma |
<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-07T05:26:51.157Z Generated by Gremlin on 2026-04-07T05:32:30.439Z
- Source: swarm/kuma.yaml Source: swarm/kuma.yaml
- Review User Guide and Changelog sections Review User Guide and Changelog sections