docs(gremlin): update kuma
This commit is contained in:
parent
fd48937c36
commit
1c0b25aa25
1 changed files with 44 additions and 62 deletions
|
|
@ -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 |
|
||||
|
||||
<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.>
|
||||
| 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
|
||||
Generated by Gremlin on 2026-04-07T05:32:30.439Z
|
||||
Source: swarm/kuma.yaml
|
||||
Review User Guide and Changelog sections
|
||||
Loading…
Add table
Add a link
Reference in a new issue