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:32:31 -05:00
parent 523ef1b24e
commit b57c538d8e
1 changed files with 54 additions and 59 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -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
---
### Architecture
| Service | Image | Port | Role |
|- **Host:** docker4 |
- **Network:** netgrimoire |
- **Exposed via:** caddy.netgrimoire.com |
- **Homepage group:** Monitoring |
| Service | Image | Port | Role | | Service | Image | Port | Role |
|- **Service** | Docker image | Host port | Function | |---------|-------|------|------|
- **Uptime Kuma:** louislam/uptime-kuma:1 | 3001 | Internal only | Display services status | - **Host:** docker4
- **AutoKuma:** ghcr.io/bigboot/autokuma:latest | - | - | Automate service monitoring | - **Network:** netgrimoire
- **Exposed via:** kuma:3001 (Caddy reverse proxy)
- **Homepage group:** Monitoring
--- ---
### Build & Configuration
## Build & Configuration
### Prerequisites ### Prerequisites
* Docker installed on docker4 - The `docker` and `docker-compose` commands are required.
### Volume Setup ### Volume Setup
```bash ```bash
mkdir -p /DockerVol/kuma:/app/data mkdir -p /DockerVol/kuma
chown -R docker4:kuma /DockerVol/kuma
``` ```
### Environment Variables ### Environment Variables
```bash ```bash
export AUTOKUMA__KUMA__URL=http://kuma:3001 AUTOKUMA__KUMA__URL=http://kuma:3001
export AUTOKUMA__KUMA__USERNAME=traveler AUTOKUMA__KUMA__USERNAME=traveler
export AUTOKUMA__KUMA__PASSWORD=F@lcon12 AUTOKUMA__KUMA__PASSWORD=F@lcon12
export AUTOKUMA__TAG_NAME=AutoKuma AUTOKUMA__TAG_NAME=AutoKuma
AUTOKUMA__DOCKER__SOURCE="DockerSwarm"
AUTOKUMA__MIGRATE="true"
# generate: openssl rand -hex 32
``` ```
### Deploy ### Deploy
@ -49,74 +49,69 @@ rm resolved.yml
docker stack services kuma docker stack services kuma
``` ```
---
### First Run ### First Run
Run `./deploy.sh` to complete the deployment process.
* After deployment, access the Uptime Kuma dashboard at https://kuma.netgrimoire.com to view service status.
--- ---
### User Guide
## User Guide
### Accessing kuma ### Accessing kuma
| Service | URL | Purpose | | 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 ### Primary Use Cases
* View the status of all services running on the swarm. - Monitoring services in NetGrimoire
### NetGrimoire Integrations ### 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 ### Monitoring
```bash ```bash
docker stack services kuma docker stack services kuma
# Check for any issues with service monitoring docker service logs -f kuma
``` ```
### Backups ### 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 ### Restore
```bash ```bash
cd services/swarm/stack/kuma
./deploy.sh ./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). ## Common Failures
Symptom: Service status displays "Down". | Symptom | Cause | Fix |
Cause: Service is down or Caddy has issues. |---------|-------|-----|
Fix: Check if the service is running and if Caddy is configured correctly. | 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". |
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
## Changelog
| Date | Commit | Summary | | 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. |
<Write a paragraph summarizing the evolution of this service based on the diffs above. If no diffs available, note that this is the initial documentation.>
--- ---
Generated by Gremlin on 2026-04-07T03:21:11.998Z ## Notes
Source: swarm/kuma.yaml - Generated by Gremlin on 2026-04-07T03:31:13.572Z
Review User Guide and Changelog sections - Source: swarm/kuma.yaml
- Review User Guide and Changelog sections