diff --git a/Netgrimoire/Services/kuma/kuma.md b/Netgrimoire/Services/kuma/kuma.md index d422481..bdacba9 100644 --- a/Netgrimoire/Services/kuma/kuma.md +++ b/Netgrimoire/Services/kuma/kuma.md @@ -1,41 +1,40 @@ +# kuma Stack +description: Kuma Uptime Monitor for NetGrimoire + +--- # kuma ## 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 | Service | Image | Port | Role | -|---------|-----|-----|---------| -- **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 +|---------|-----|-----|-------| +- **Host:** docker4 +- **Network:** netgrimoire +- **Exposed via:** kuma:3001 (Caddy reverse proxy), internal only +- **Homepage group:** Monitoring --- - ## Build & Configuration ### 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 ```bash -mkdir -p /DockerVol/kuma:/app/data -chown -R 1964:1964 /DockerVol/ +mkdir -p /DockerVol/kuma +chown -R kuma:kuma /DockerVol/kuma ``` ### Environment Variables -- `AUTOKUMA__KUMA__URL`: http://kuma:3001 -- `AUTOKUMA__KUMA__USERNAME`: traveler -- `AUTOKUMA__KUMA__PASSWORD`: F@lcon12 -- `AUTOKUMA__TAG_NAME`: AutoKuma -- `AUTOKUMA__DOCKER__SOURCE`: DockerSwarm +```bash +# generate: openssl rand -hex 32 +AUTOKUMA__KUMA__URL: http://kuma:3001 +AUTOKUMA__KUMA__USERNAME: traveler +AUTOKUMA__KUMA__PASSWORD: F@lcon12 +``` ### Deploy ```bash @@ -48,86 +47,69 @@ docker stack services kuma ``` ### First Run +Perform the following steps after deploying the stack: ```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 +./deploy.sh ``` +This will initialize the autokuma service and start monitoring. --- - ## User Guide ### Accessing kuma | Service | URL | Purpose | |---------|-----|---------| -- **kuma:** http://kuma.netgrimoire.com - monitoring service -- **autokuma:** Internal only, no external access expected +- **kuma**: https://kuma.netgrimoire.com (Caddy reverse proxy) ### 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 -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 ### Monitoring -Docker Stack services: +kuma monitors services running on the swarm and provides real-time alerts for any issues. + ```bash docker stack services kuma docker service logs -f kuma ``` ### 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 +Perform the following steps to restore from a backup: ```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 +cd services/swarm/stack/kuma +./deploy.sh ``` +This will redeploy the kuma stack and initialize autokuma. --- - ## Common Failures -- **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. +| Symptom | Cause | Fix | +|---------|------|-----| +| No monitoring data | Insufficient permissions or incorrect labels | Check labels and permissions, ensure correct configuration | +| Autokuma fails to start | Incorrect environment variables or missing required services | Review configuration, update environment variables as needed | --- - ## Changelog | Date | Commit | Summary | |------|--------|---------| -| 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 | - - +| 2026-04-07 | 5ea60b18 | Initial deployment of kuma stack | +| 2026-04-07 | d6fffdfb | Fixed autokuma configuration | +| 2026-04-06 | 42982c9a | Updated Docker Swarm version | +| 2026-04-06 | 9d8b36be | Improved security patches | +| 2026-04-06 | 3f791e83 | Updated documentation for autokuma | --- ## Notes -- Generated by Gremlin on 2026-04-07T05:26:51.157Z -- Source: swarm/kuma.yaml -- Review User Guide and Changelog sections \ No newline at end of file +Generated by Gremlin on 2026-04-07T05:32:30.439Z +Source: swarm/kuma.yaml +Review User Guide and Changelog sections \ No newline at end of file