---
title: gatus Stack
description: Service Monitor for NetGrimoire
published: true
date: 2026-04-30T18:35:55.433Z
tags: docker,swarm,gatus,netgrimoire
editor: markdown
dateCreated: 2026-04-30T18:35:55.433Z
---

# gatus

## Overview
The gatus stack is a Docker Swarm-based service monitor for NetGrimoire. It provides real-time monitoring and alerts for critical services, including Gatus itself.

## Architecture

| Service | Image | Port | Role |
|---------|-------|------|------|
- **Host:** docker4
- **Network:** netgrimoire
- **Exposed via:** status.netgrimoire.com, gatus:8080 (Internal only)
- **Homepage group:** Monitoring

---

## Build & Configuration

### Prerequisites
- Docker Swarm manager and worker nodes must be running.
- The `gatus-stack.yml` file should be present in the root directory.

### Volume Setup
```bash
mkdir -p /DockerVol/gatus/config
mkdir -p /DockerVol/gatus/data
chown -R gatus:gatus /DockerVol/gatus
```

### Environment Variables
```bash
PUID=1964
PGID=1964
TZ=America/Chicago
GATUS_CONFIG_PATH=/config/config.yaml

CADDY_STATUSNETGRIMOIRE_COM=status.netgrimoire.com
CADDY_REVERSE_PROXY=gatus:8080
CADDY_IMPORT_1=crowdsec
CADDY_IMPORT_2=authentik

MONITOR_NAME=Gatus
MONITOR_URL=https://status.netgrimoire.com
MONITOR_TYPE=http

HOMEPAGE_GROUP=Monitoring
HOMEPAGE_NAME=Gatus
HOMEPAGE_ICON=gatus.png
HOMEPAGE_HREF=https://status.netgrimoire.com
HOMEPAGE_DESCRIPTION=Service Monitor
```

### Deploy
```bash
cd services/swarm/stack/gatus
set -a && source .env && set +a
docker stack config --compose-file gatus-stack.yml > resolved.yml
docker stack deploy --compose-file resolved.yml gatus
rm resolved.yml
docker stack services gatus
```

### First Run
- Initialize the database and create any necessary configuration files.

---

## User Guide

### Accessing gatus
| Service | URL |
|---------|-----|
- Gatus: https://status.netgrimoire.com (External), http://localhost:8080 (Internal)

### Primary Use Cases
- Monitor system services for health and performance issues.
- Receive alerts and notifications when services go down or experience errors.

### NetGrimoire Integrations
- Connects to other services in NetGrimoire via environment variables and labels.

---

## Operations

### Monitoring
```bash
docker stack services gatus
docker service logs -f gatus
```

### Backups
- Critical data should be backed up to a secure location.
- The `gatus-stack.yml` file should be version-controlled.

### Restore
```bash
cd services/swarm/stack/gatus
./deploy.sh
```

---

## Common Failures
| Failure Mode | Symptoms | Cause | Fix |
|-------------|----------|------|-----|
1. Service not starting | No gatus service running | Incorrect `docker stack deploy` command | Verify that the `gatus-stack.yml` file is correct and run the deployment command again.
2. Caddy unable to connect to netgrimoire | Connection errors when accessing status.netgrimoire.com | Incorrect CADDY_STATUSNETGRIMOIRE_COM environment variable | Update the `CADDY_STATUSNETGRIMOIRE_COM` environment variable to match the actual domain.

---

## Changelog

| Date | Commit | Summary |
|------|--------|---------|
| 2026-04-30 | 203bf00b | Initial documentation for gatus stack. |
| 2026-04-30 | 6de54336 | Added environment variables for Caddy configuration. |
| 2026-04-30 | 72ae0553 | Updated `docker-compose.yml` to include latest dependencies. |
| 2026-04-30 | aa844e07 | Changed deployment command to use `resolved.yml`. |
| 2026-04-30 | 2d8b1bd8 | Improved volume setup instructions for gatus. |
| 2026-04-30 | 85c56402 | Added First Run section with post-deploy steps. |
| 2026-04-22 | 0b0d8565 | Fixed typo in `docker-compose.yml`. |
| 2026-04-22 | 2e55179e | Improved `docker stack deploy` command for stability. |

---

## Notes
- Generated by Gremlin on 2026-04-30T18:35:55.433Z
- Source: swarm/gatus.yaml
- Review User Guide and Changelog sections