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-06 22:23:23 -05:00
parent f9a8b68fdb
commit 523ef1b24e
1 changed files with 68 additions and 41 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -1,34 +1,42 @@
# kuma Stack
## Overview
The kuma Stack is a monitoring service in NetGrimoire that provides real-time monitoring of services and infrastructure. The stack consists of two main services: kuma, which is the core monitoring service, and autokuma, which automates the process of adding new services to the monitor.
description: Services Monitor
## Architecture
---
### 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 |
| Service | Image | Port | Role |
|---------|-------|------|------|
- **Host:** docker4
- **Network:** netgrimoire
- **Exposed via:** kuma.netgrimoire.com, uptime-kuma.netgrimoire.com
- **Homepage group:** Monitoring
|- **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 |
## Build & Configuration
---
### Build & Configuration
### Prerequisites
This stack requires Docker Swarm to be configured and the `docker.stack` command to be available.
* Docker installed on docker4
### Volume Setup
```bash
mkdir -p /DockerVol/kuma
chown -R user:kuma /DockerVol/kuma
mkdir -p /DockerVol/kuma:/app/data
```
### Environment Variables
```bash
# generate: openssl rand -hex 32
AUTOKUMA__KUMA__URL=https://kuma:3001
AUTOKUMA__KUMA__USERNAME=traveler
AUTOKUMA__KUMA__PASSWORD=F@lcon12
export AUTOKUMA__KUMA__URL=http://kuma:3001
export AUTOKUMA__KUMA__USERNAME=traveler
export AUTOKUMA__KUMA__PASSWORD=F@lcon12
export AUTOKUMA__TAG_NAME=AutoKuma
```
### Deploy
@ -41,55 +49,74 @@ rm resolved.yml
docker stack services kuma
```
---
### First Run
After the first deployment, you need to run `./deploy.sh` to complete the setup.
## User Guide
* After deployment, access the Uptime Kuma dashboard at https://kuma.netgrimoire.com to view service status.
---
### User Guide
### Accessing kuma
| Service | URL | Purpose |
|---------|-----|---------|
- **kuma**: https://kuma.netgrimoire.com (Monitor)
- **uptime-kuma**: https://kuma.netgrimoire.com (Dashboard)
|- **Uptime Kuma:** https://kuma.netgrimoire.com | Display services status |
### Primary Use Cases
This stack provides real-time monitoring of services and infrastructure. It can be used to monitor individual services or the entire NetGrimoire environment.
* View the status of all services running on the swarm.
### NetGrimoire Integrations
The kuma Stack connects to other services in NetGrimoire, such as Caddy for reverse proxying and Uptime Kuma for monitoring.
* Uptime Kuma is connected to all services in the swarm via Caddy reverse proxy and Uptime Kuma labels (caddy.dig.kuma, kuma.*).
## Operations
---
### Operations
### Monitoring
```bash
docker stack services kuma
docker service logs -f kuma
# Check for any issues with service monitoring
```
### Backups
Critical data should be backed up regularly. The `/DockerVol/kuma` volume is recommended for storing backups.
Critical: Regular backups of `/DockerVol/kuma` are essential to ensure data integrity.
### Restore
If the stack needs to be restored, you can run `./deploy.sh` after deleting the existing `resolved.yml` file.
```bash
./deploy.sh
# Re-deploy the `kuma` stack in case of a failure.
```
## Common Failures
---
### Common Failures
| Symptom | Cause | Fix |
|---------|-------|-----|
- Stack does not deploy | Missing dependencies | Run `docker-compose up -d` and wait for it to complete. |
- Monitoring not working | Inactive kuma service | Check the status of the kuma service with `docker stack services kuma`. Restart the service if necessary. |
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.
## Changelog
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.
---
### Changelog
| Date | Commit | Summary |
|------|--------|---------|
| 2026-04-06 | 3f791e83 | Initial deployment |
| 2026-04-04 | 5b03dbf9 | Update to use Caddy reverse proxying |
| 2026-04-04 | 6f0000c4 | Add autokuma service for automated monitoring |
| 2026-03-30 | e58b778a | Initial deployment |
| 2026-03-30 | 6f369592 | Update to use Docker Swarm stack configuration |
|- 2026-04-06 | 9d8b36be | Initial documentation for kuma Stack. |
| - | - | - |
## Notes
Generated by Gremlin on 2026-04-07T03:20:50.864Z.
---
Generated by Gremlin on 2026-04-07T03:21:11.998Z
Source: swarm/kuma.yaml
Review User Guide and Changelog sections