docs(gremlin): update gatus
This commit is contained in:
parent
361570965e
commit
3218dd2ac7
1 changed files with 54 additions and 40 deletions
|
|
@ -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 `<caddy domains from labels>`
|
||||
- **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
|
||||
Loading…
Add table
Add a link
Reference in a new issue