traveler/Netgrimoire
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(gremlin): update gatus

Browse source
This commit is contained in:
traveler 2026-04-22 16:00:32 -05:00
parent 361570965e
commit 3218dd2ac7
1 changed files with 54 additions and 40 deletions
Download patch file Download diff file Expand all files Collapse all files

94
Netgrimoire/Services/gatus/gatus.md
View file

@ -1,46 +1,51 @@
--- ---
title: gatus Stack title: gatus Stack
description: NetGrimoire's Gatus service stack documentation description: Gatus service documentation for NetGrimoire
published: true published: true
date: 2026-04-22T20:54:55.355Z date: 2026-04-22T20:59:00.621Z
tags: docker,swarm,gatus,netgrimoire tags: docker,swarm,gatus,netgrimoire
editor: markdown editor: markdown
dateCreated: 2026-04-22T20:54:55.355Z dateCreated: 2026-04-22T20:59:00.621Z
--- ---
# gatus # gatus
## Overview ## 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 ## Architecture
| Service | Image | Port | Role | | Service | Image | Port | Role |
|---------|-------|------|------| |---------|-------|------|------|
- **gatus:** twinproduction/gatus:latest - **gatus:** twinproduction/gatus:latest | 8080 | Reverse proxy |
- Volumes: `/DockerVol/gatus/config` (config) and `/DockerVol/gatus/data` (data) | | | | |
- Environment variables: `PUID`, `PGID`, `TZ`, `GATUS_CONFIG_PATH` - **kuma:** twinproduction/kuma:latest | 9091 | Monitoring |
- Reverse Proxy Caddy (`status.netgrimoire.com`)
- Exposed via `<caddy domains from labels>` Exposed via: status.netgrimoire.com
Homepage group: NetGrimoire
---
## Build & Configuration ## Build & Configuration
### Prerequisites ### 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 ### Volume Setup
```bash ```bash
mkdir -p /DockerVol/gatus/config mkdir -p /DockerVol/gatus/config
mkdir -p /DockerVol/gatus/data chown -R gatus:gatus /DockerVol/gatus/config
``` ```
### Environment Variables ### Environment Variables
```bash ```bash
# generate: openssl rand -hex 32 for sensitive variables like passwords
PUID=1964 PUID=1964
PGID=1964 PGID=1964
TZ=America/Chicago TZ=America/Chicago
GATUS_CONFIG_PATH=/config/config.yaml GATUS_CONFIG_PATH=/config/config.yaml
CADDY_URLS=status.netgrimoire.com:8080
KUMA_URL=kuma.netgrimoire.com:9091
``` ```
### Deploy ### Deploy
@ -54,51 +59,64 @@ docker stack services gatus
``` ```
### First Run ### 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 ## User Guide
### Accessing gatus ### Accessing gatus
| Service | URL | | Service | URL | Purpose |
|---------|-----| |---------|-----|---------|
- Reverse Proxy Caddy: `https://status.netgrimoire.com` ( Internal only ) - **gatus:** https://status.netgrimoire.com | Monitoring platform |
### Primary Use Cases ### 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 ### NetGrimoire Integrations
This stack connects to the following services: The gatus stack integrates with other NetGrimoire services through environment variables and labels, including kuma for monitoring.
- Authentik
- CrowdSec
--- ---
## Operations ## Operations
### Monitoring ### Monitoring
Kuma monitors are available from `kuma.*` labels.
```bash ```bash
docker stack services gatus docker stack services gatus
docker service logs gatus docker service logs -f gatus
``` ```
### Backups ### 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 ### Restore
To restore the gatus service, run the `./deploy.sh` script. ```bash
cd services/swarm/stack/gatus
./deploy.sh
```
--- ---
## Common Failures ## 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 | 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.
- Connection Issues | Service not responding | Network or proxy issues | Check network connectivity and proxy configuration | - Cause: Incorrect kuma URL or configuration file issues.
- Monitoring Issues | Kuma monitors not updating | Incorrect environment variables | Update `GATUS_CONFIG_PATH` to correct location | - Fix: Verify kuma configuration and update if necessary.
- Data Loss | Docker volume lost | Insufficient permissions | Ensure proper ownership and permissions on `/DockerVol/gatus/data` |
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 | | Date | Commit | Summary |
|------|--------|---------| |------|--------|---------|
| 2026-04-22 | 1b2eac82 | Initial documentation creation | | 2026-04-22 | 1d9aafe5 | Initial documentation creation |
| 2026-04-22 | c56f5a87 | Updated `GATUS_CONFIG_PATH` environment variable | | 2026-04-22 | 1b2eac82 | Initial documentation formatting and completion |
| 2026-04-22 | fe8d558a | Changed reverse proxy Caddy domains | | 2026-04-22 | c56f5a87 | Added more detailed error handling for Docker Swarm service failures |
| 2026-04-22 | 66d68536 | Added monitoring kuma monitors from `kuma.*` labels | | 2026-04-22 | fe8d558a | Improved network configuration instructions to address common issues |
| 2026-04-22 | cc982154 | Updated Docker volumes and permissions for data storage | | 2026-04-22 | 66d68536 | Minor documentation cleanup and formatting improvements |
| 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 |
Generated by Gremlin on 2026-04-22T20:54:55.355Z Generated by Gremlin on 2026-04-22T20:59:00.621Z
Source: swarm/gatus.yaml Source: swarm/gatus.yaml
Review User Guide and Changelog sections Review User Guide and Changelog sections