115 lines
No EOL
3.4 KiB
Markdown
115 lines
No EOL
3.4 KiB
Markdown
# 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
|
|
```bash
|
|
mkdir -p /DockerVol/kuma
|
|
chown -R kuma:kuma /DockerVol/kuma
|
|
```
|
|
|
|
### Environment Variables
|
|
```bash
|
|
# generate: openssl rand -hex 32
|
|
AUTOKUMA__KUMA__URL: http://kuma:3001
|
|
AUTOKUMA__KUMA__USERNAME: traveler
|
|
AUTOKUMA__KUMA__PASSWORD: F@lcon12
|
|
```
|
|
|
|
### Deploy
|
|
```bash
|
|
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:
|
|
```bash
|
|
./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.
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
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 |