3.4 KiB
kuma Stack
description: Kuma Uptime Monitor for NetGrimoire
kuma
Overview
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 |
|---|
- Host: docker4
- Network: netgrimoire
- Exposed via: kuma:3001 (Caddy reverse proxy), internal only
- Homepage group: Monitoring
Build & Configuration
Prerequisites
To deploy this stack, ensure you have Docker Swarm installed and running on your manager node.
Volume Setup
mkdir -p /DockerVol/kuma
chown -R kuma:kuma /DockerVol/kuma
Environment Variables
# generate: openssl rand -hex 32
AUTOKUMA__KUMA__URL: http://kuma:3001
AUTOKUMA__KUMA__USERNAME: traveler
AUTOKUMA__KUMA__PASSWORD: F@lcon12
Deploy
cd services/swarm/stack/kuma
set -a && source .env && set +a
docker stack config --compose-file kuma-stack.yml > resolved.yml
docker stack deploy --compose-file resolved.yml kuma
rm resolved.yml
docker stack services kuma
First Run
Perform the following steps after deploying the stack:
./deploy.sh
This will initialize the autokuma service and start monitoring.
User Guide
Accessing kuma
| Service | URL | Purpose |
|---|
- kuma: https://kuma.netgrimoire.com (Caddy reverse proxy)
Primary Use Cases
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 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
kuma monitors services running on the swarm and provides real-time alerts for any issues.
docker stack services kuma
docker service logs -f kuma
Backups
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:
cd services/swarm/stack/kuma
./deploy.sh
This will redeploy the kuma stack and initialize autokuma.
Common Failures
| 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 | 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:32:30.439Z Source: swarm/kuma.yaml Review User Guide and Changelog sections