diff --git a/Netgrimoire/Services/kuma/kuma.md b/Netgrimoire/Services/kuma/kuma.md index 4bfc627..fc8a872 100644 --- a/Netgrimoire/Services/kuma/kuma.md +++ b/Netgrimoire/Services/kuma/kuma.md @@ -1,42 +1,42 @@ -# kuma Stack +# kuma -description: Services Monitor +## Overview +The kuma stack is a Docker Swarm-based monitoring service used in NetGrimoire, providing real-time services monitoring and automation. --- -### Overview -The `kuma` stack is a collection of services that provide monitoring capabilities in NetGrimoire. It includes Uptime Kuma, which displays the status of all services running on the swarm, and AutoKuma, which automates the process of adding new services to the monitoring system. - ---- -### Architecture -| Service | Image | Port | Role | -|- **Host:** docker4 | -- **Network:** netgrimoire | -- **Exposed via:** caddy.netgrimoire.com | -- **Homepage group:** Monitoring | +## Architecture | Service | Image | Port | Role | -|- **Service** | Docker image | Host port | Function | -- **Uptime Kuma:** louislam/uptime-kuma:1 | 3001 | Internal only | Display services status | -- **AutoKuma:** ghcr.io/bigboot/autokuma:latest | - | - | Automate service monitoring | +|---------|-------|------|------| +- **Host:** docker4 +- **Network:** netgrimoire +- **Exposed via:** kuma:3001 (Caddy reverse proxy) +- **Homepage group:** Monitoring --- -### Build & Configuration + +## Build & Configuration ### Prerequisites -* Docker installed on docker4 +- The `docker` and `docker-compose` commands are required. ### Volume Setup ```bash -mkdir -p /DockerVol/kuma:/app/data +mkdir -p /DockerVol/kuma +chown -R docker4:kuma /DockerVol/kuma ``` ### Environment Variables ```bash -export AUTOKUMA__KUMA__URL=http://kuma:3001 -export AUTOKUMA__KUMA__USERNAME=traveler -export AUTOKUMA__KUMA__PASSWORD=F@lcon12 -export AUTOKUMA__TAG_NAME=AutoKuma +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 ``` ### Deploy @@ -49,74 +49,69 @@ rm resolved.yml docker stack services kuma ``` ---- ### First Run - -* After deployment, access the Uptime Kuma dashboard at https://kuma.netgrimoire.com to view service status. +Run `./deploy.sh` to complete the deployment process. --- -### User Guide + +## User Guide ### Accessing kuma | Service | URL | Purpose | -|- **Uptime Kuma:** https://kuma.netgrimoire.com | Display services status | +- **kuma:** https://kuma.netgrimoire.com (Caddy reverse proxy) +- **AutoKuma:** https://auto.kuma.netgrimoire.com (Caddy reverse proxy) ### Primary Use Cases -* View the status of all services running on the swarm. +- Monitoring services in NetGrimoire ### NetGrimoire Integrations -* Uptime Kuma is connected to all services in the swarm via Caddy reverse proxy and Uptime Kuma labels (caddy.dig.kuma, kuma.*). +- Integrates with other NetGrimoire services, such as Docker Swarm and Caddy. --- -### Operations + +## Operations ### Monitoring ```bash docker stack services kuma -# Check for any issues with service monitoring +docker service logs -f kuma ``` ### Backups -Critical: Regular backups of `/DockerVol/kuma` are essential to ensure data integrity. +- Critical: /DockerVol/kuma (automatically backed up by Docker Swarm) +- Reconstructable: No specific backup paths needed ### Restore ```bash +cd services/swarm/stack/kuma ./deploy.sh -# Re-deploy the `kuma` stack in case of a failure. ``` --- -### Common Failures -1. **Service not responding**: The service is down, or there's an issue with the reverse proxy (Caddy). - Symptom: Service status displays "Down". - Cause: Service is down or Caddy has issues. - Fix: Check if the service is running and if Caddy is configured correctly. - -2. **No data available**: No data is being sent to Uptime Kuma, or there's an issue with data forwarding. - Symptom: Status displays "No data". - Cause: No data is being sent to Uptime Kuma or there's an issue with data forwarding. - Fix: Check if data forwarding is enabled and that the service is sending data correctly. - -3. **AutoKuma not working**: AutoKuma is unable to add new services to the monitoring system. - Symptom: Services are not appearing in Uptime Kuma. - Cause: AutoKuma configuration or service setup issues. - Fix: Check AutoKuma configuration and ensure that services are properly set up. - -4. **Uptime Kuma metrics**: Uptime Kuma is not displaying expected metrics (e.g., load, memory usage). - Symptom: Metrics are missing from the status display. - Cause: Configuration or data issues. - Fix: Check Uptime Kuma configuration and ensure that expected metrics are being collected. +## 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". | --- -### Changelog + +## Changelog | Date | Commit | Summary | -|- 2026-04-06 | 9d8b36be | Initial documentation for kuma Stack. | -| - | - | - | +|------|--------|---------| +| 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. | + + --- -Generated by Gremlin on 2026-04-07T03:21:11.998Z -Source: swarm/kuma.yaml -Review User Guide and Changelog sections \ No newline at end of file +## Notes +- Generated by Gremlin on 2026-04-07T03:31:13.572Z +- Source: swarm/kuma.yaml +- Review User Guide and Changelog sections \ No newline at end of file