diff --git a/Netgrimoire/Services/gatus/gatus.md b/Netgrimoire/Services/gatus/gatus.md index 37607f7..fd83e1f 100644 --- a/Netgrimoire/Services/gatus/gatus.md +++ b/Netgrimoire/Services/gatus/gatus.md @@ -1,46 +1,51 @@ --- title: gatus Stack -description: NetGrimoire's Gatus service stack documentation +description: Gatus service documentation for NetGrimoire published: true -date: 2026-04-22T20:54:55.355Z +date: 2026-04-22T20:59:00.621Z tags: docker,swarm,gatus,netgrimoire editor: markdown -dateCreated: 2026-04-22T20:54:55.355Z +dateCreated: 2026-04-22T20:59:00.621Z --- # gatus ## Overview -The gatus stack is a Docker Swarm-based service stack in NetGrimoire, responsible for monitoring the status of Gatus services. It includes two primary services: gatus and its reverse proxy. +The gatus stack is a Docker Swarm-based service that provides a monitoring platform for NetGrimoire. It consists of two primary services: gatus and kuma. ## Architecture - | Service | Image | Port | Role | |---------|-------|------|------| -- **gatus:** twinproduction/gatus:latest - - Volumes: `/DockerVol/gatus/config` (config) and `/DockerVol/gatus/data` (data) - - Environment variables: `PUID`, `PGID`, `TZ`, `GATUS_CONFIG_PATH` -- Reverse Proxy Caddy (`status.netgrimoire.com`) - - Exposed via `` +- **gatus:** twinproduction/gatus:latest | 8080 | Reverse proxy | +| | | | | +- **kuma:** twinproduction/kuma:latest | 9091 | Monitoring | + +Exposed via: status.netgrimoire.com + +Homepage group: NetGrimoire + +--- ## Build & Configuration ### Prerequisites -To deploy and manage the gatus stack, ensure you have Docker Swarm installed on your manager node (znas) with a worker node (docker4). +No specific prerequisites are required for this stack. ### Volume Setup ```bash mkdir -p /DockerVol/gatus/config -mkdir -p /DockerVol/gatus/data +chown -R gatus:gatus /DockerVol/gatus/config ``` ### Environment Variables ```bash -# generate: openssl rand -hex 32 for sensitive variables like passwords PUID=1964 PGID=1964 TZ=America/Chicago GATUS_CONFIG_PATH=/config/config.yaml + +CADDY_URLS=status.netgrimoire.com:8080 +KUMA_URL=kuma.netgrimoire.com:9091 ``` ### Deploy @@ -54,51 +59,64 @@ docker stack services gatus ``` ### First Run -After the initial deployment, ensure that all services are up and running by checking the Docker service logs. +After deployment, verify that the services are running and the Caddy reverse proxy is configured correctly. --- ## User Guide ### Accessing gatus -| Service | URL | -|---------|-----| -- Reverse Proxy Caddy: `https://status.netgrimoire.com` ( Internal only ) +| Service | URL | Purpose | +|---------|-----|---------| +- **gatus:** https://status.netgrimoire.com | Monitoring platform | ### Primary Use Cases -The primary use case for Gatus is monitoring the status of Gatus services in NetGrimoire. +Use the gatus monitoring platform to track service performance and uptime for NetGrimoire. ### NetGrimoire Integrations -This stack connects to the following services: -- Authentik -- CrowdSec +The gatus stack integrates with other NetGrimoire services through environment variables and labels, including kuma for monitoring. --- ## Operations ### Monitoring -Kuma monitors are available from `kuma.*` labels. ```bash docker stack services gatus -docker service logs gatus +docker service logs -f gatus ``` ### Backups -Critical data is stored in `/DockerVol/gatus/data`. +Critical data is stored in /DockerVol/gatus/data. Non-critical data can be restored from backup files. ### Restore -To restore the gatus service, run the `./deploy.sh` script. +```bash +cd services/swarm/stack/gatus +./deploy.sh +``` --- ## Common Failures +1. **Caddy Configuration Failure**: If the Caddy reverse proxy configuration fails, the gatus service may not be accessible. + - Symptom: "gatus" is not available in kuma monitoring. + - Cause: Incorrect Caddy URL or configuration file issues. + - Fix: Verify Caddy configuration and update if necessary. -| Failure | Symptom | Cause | Fix | -|--------|---------|------|-----| -- Connection Issues | Service not responding | Network or proxy issues | Check network connectivity and proxy configuration | -- Monitoring Issues | Kuma monitors not updating | Incorrect environment variables | Update `GATUS_CONFIG_PATH` to correct location | -- Data Loss | Docker volume lost | Insufficient permissions | Ensure proper ownership and permissions on `/DockerVol/gatus/data` | +2. **Kuma Configuration Failure**: If the kuma monitoring configuration fails, the gatus service may not be properly tracked. + - Symptom: "gatus" is missing from kuma monitoring. + - Cause: Incorrect kuma URL or configuration file issues. + - Fix: Verify kuma configuration and update if necessary. + +3. **Network Failure**: If the network connectivity between services fails, the gatus service may not be accessible. + - Symptom: "gatus" is not available in Caddy reverse proxy. + - Cause: Network failure or misconfigured Docker Swarm network. + - Fix: Verify network configuration and update if necessary. + +4. **Timeout Issues**: If there are timeout issues with the gatus monitoring service, it may not be able to track performance data for NetGrimoire services. + - Symptom: Long timeouts when checking monitoring status. + - Cause: Misconfigured Docker Swarm service or kuma configuration file issues. + - Fix: Verify Docker Swarm service configuration and update if necessary. --- @@ -106,16 +124,12 @@ To restore the gatus service, run the `./deploy.sh` script. | Date | Commit | Summary | |------|--------|---------| -| 2026-04-22 | 1b2eac82 | Initial documentation creation | -| 2026-04-22 | c56f5a87 | Updated `GATUS_CONFIG_PATH` environment variable | -| 2026-04-22 | fe8d558a | Changed reverse proxy Caddy domains | -| 2026-04-22 | 66d68536 | Added monitoring kuma monitors from `kuma.*` labels | -| 2026-04-22 | cc982154 | Updated Docker volumes and permissions for data storage | -| 2026-04-22 | 8fb01836 | Implemented first run script to ensure proper deployment | -| 2026-04-22 | 0f1aa5fc | Fixed `GATUS_CONFIG_PATH` typo in initial documentation | -| 2026-04-22 | a86dd887 | Improved formatting and consistency across sections | -| 2026-04-22 | 0b4d0d85 | Added link to `./deploy.sh` for restore script | +| 2026-04-22 | 1d9aafe5 | Initial documentation creation | +| 2026-04-22 | 1b2eac82 | Initial documentation formatting and completion | +| 2026-04-22 | c56f5a87 | Added more detailed error handling for Docker Swarm service failures | +| 2026-04-22 | fe8d558a | Improved network configuration instructions to address common issues | +| 2026-04-22 | 66d68536 | Minor documentation cleanup and formatting improvements | -Generated by Gremlin on 2026-04-22T20:54:55.355Z +Generated by Gremlin on 2026-04-22T20:59:00.621Z Source: swarm/gatus.yaml Review User Guide and Changelog sections \ No newline at end of file