Gatus mit Docker installieren: Entwicklerorientiertes Status-Dashboard für HTTP, DNS und ICMP
Gatus ist ein schlankes, konfigurationsgesteuertes Status-Dashboard, das Dienste per HTTP, DNS, TCP und ICMP überwacht und bei Schwellenwert-Verletzungen über Slack, PagerDuty oder E-Mail alarmiert. Die Anleitung zeigt Einrichtung, Alerting und Absicherung mit Docker Compose.
Werbung Mit * markierte Links sind Werbelinks: Bei einem Kauf erhalten wir eine Provision, der Preis bleibt gleich. Als Amazon-Partner verdiene ich an qualifizierten Verkäufen. Mehr dazu

Wer Dienste professionell betreibt, braucht mehr als ein einfaches „ist der Server up?“-Skript. Gatus ist ein entwicklerorientiertes, selbst gehostetes Health-Dashboard, das Endpunkte per HTTP/HTTPS, ICMP, TCP, DNS, WebSocket, gRPC und weiteren Protokollen überwacht. Es bewertet Antworten anhand konfigurierbarer Bedingungen, etwa Status-Code, Antwortzeit oder Zertifikatsablauf, und löst bei definierten Schwellenwerten Alarme über mehr als 30 Provider aus: Slack, PagerDuty, E-Mail, Discord, Teams oder Telegram. Gatus vereint öffentliche Statusseite und internes Monitoring in einem Container und eignet sich für KMU, die ihre Überwachung als Konfigurationsdatei versionieren möchten.
Voraussetzungen
- Docker Engine 20.10+ und Docker Compose v2 (Befehl:
docker compose, nichtdocker-compose) auf einem Linux-Host, einer VM oder einem NAS mit Docker-Unterstützung. Noch nicht installiert? Siehe Docker und Docker Compose auf Linux installieren. - Mindestens 50 MB RAM und 100 MB freier Speicher (ohne Datenbank); für die PostgreSQL-Variante zusätzlich ~256 MB RAM.
- Einen Texteditor (nano, VS Code o. ä.) für
config.yamlund.env. - curl oder wget zum Testen der Endpunkte sowie einen Browser für das Dashboard.
- Optional: Slack-Webhook-URL, PagerDuty Integration-Key oder SMTP-Zugangsdaten für Alerting-Tests.
- Optional: einen Reverse Proxy (z. B. Nginx Proxy Manager oder Traefik) für HTTPS-Zugriff von außen. Grundlagen dazu in Traefik als Docker-Reverse-Proxy einrichten.
Schritt 1: Projektordner und Verzeichnisstruktur anlegen
Legen Sie einen eigenen Ordner mit Unterverzeichnis für die Konfiguration an und erzeugen Sie die leere Datei config.yaml vorab. Grund: Existiert die Zieldatei beim Mount nicht, legt Docker an ihrer Stelle ein Verzeichnis an, und Gatus kann die Konfiguration nicht lesen.
$ mkdir -p /opt/gatus/config
$ touch /opt/gatus/config/config.yaml
$ cd /opt/gatusDie resultierende Verzeichnisstruktur sieht so aus:
/opt/gatus/
├── compose.yaml
├── .env
└── config/
└── config.yamlls -la /opt/gatus/config/ muss config.yaml als reguläre Datei (nicht als Verzeichnis) anzeigen. Der Typ in der ersten Spalte muss -rw sein, nicht drw.
Schritt 2: Secrets in der .env-Datei sichern
Secrets wie Webhook-URLs und Passwörter gehören nie direkt in die Konfigurationsdatei. Gatus löst alle ${VAR_NAME}-Referenzen in config.yaml automatisch aus Umgebungsvariablen auf, die .env-Datei im Projektordner ist der sichere Ablageort.
# /opt/gatus/.env
# Nur die Variablen eintragen, die Sie tatsächlich nutzen.
# Ungenutzte Zeilen können leer bleiben oder auskommentiert werden.
# Slack Alerting (optional)
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
# PagerDuty Alerting (optional)
PAGERDUTY_KEY=ihr-pagerduty-integration-key
# E-Mail Alerting via SMTP (optional)
# Bei Gmail: App-Passwort verwenden, kein Account-Passwort!
SMTP_PASSWORD=ihr-app-passwortDanach unbedingt .env zur .gitignore hinzufügen, damit Secrets nicht ins Repository gelangen:
$ echo ".env" >> /opt/gatus/.gitignorecat /opt/gatus/.env zeigt die gesetzten Variablen. Prüfen Sie, dass die Datei keine Leerzeichen um das =-Zeichen enthält, da Docker Compose diese Syntax nicht toleriert.
Schritt 3: Konfigurationsdatei config.yaml erstellen
Die gesamte Steuerung von Gatus erfolgt über config/config.yaml. Hier werden Storage, Web-Einstellungen, Alerting-Provider und die zu überwachenden Endpunkte definiert. Das folgende Beispiel enthält einen HTTP-Endpunkt mit Slack-Alerting, einen DNS-Check und einen ICMP-Ping, drei typische Monitoring-Szenarien.
Wichtig bei Bedingungen: Schreiben Sie immer Leerzeichen um den Operator, also [STATUS] == 200 und nicht [STATUS]==200. Ohne Leerzeichen erkennt Gatus keinen Operator, wertet die Bedingung als „invalid condition“ und meldet den Endpunkt dauerhaft als gestört.
# /opt/gatus/config/config.yaml
# ── Datenpersistenz (SQLite empfohlen für Einzel-Host) ──────────────────
storage:
type: sqlite
path: /data/gatus.db
# ── Web-Einstellungen ────────────────────────────────────────────────────
web:
address: "0.0.0.0"
port: 8080
# ── Alerting-Provider (nur konfigurieren, was Sie nutzen) ─────────────────
alerting:
slack:
webhook-url: "${SLACK_WEBHOOK_URL}"
default-alert:
failure-threshold: 3 # Alert nach 3 aufeinanderfolgenden Fehlern
success-threshold: 2 # Entwarnung nach 2 Erfolgen
pagerduty:
integration-key: "${PAGERDUTY_KEY}"
default-alert:
failure-threshold: 5
success-threshold: 3
email:
from: "gatus@example.com"
username: "ihre-adresse@gmail.com"
password: "${SMTP_PASSWORD}"
host: "smtp.gmail.com"
port: 587
to: "team@example.com"
# ── Zu überwachende Endpunkte ────────────────────────────────────────────
endpoints:
- name: Meine API
group: produktion
url: "https://api.example.com/health"
interval: 30s
conditions:
- "[STATUS] == 200"
- "[RESPONSE_TIME] < 500"
- "[CERTIFICATE_EXPIRATION] > 48h"
alerts:
- type: slack
failure-threshold: 3
success-threshold: 2
- name: DNS-Check Google
url: "8.8.8.8"
interval: 5m
dns:
query-name: "example.com"
query-type: "A"
conditions:
- "[DNS_RCODE] == NOERROR"
- name: ICMP-Ping Gateway
url: "icmp://192.168.1.1"
interval: 1m
conditions:
- "[CONNECTED] == true"cat /opt/gatus/config/config.yaml, die Datei muss vollständig und korrekt eingerückt sein. YAML ist whitespace-sensitiv; Tabulatoren sind verboten, nur Leerzeichen verwenden.
Schritt 4: compose.yaml erstellen
Die folgende compose.yaml nutzt das offizielle GHCR-Image ghcr.io/twin/gatus:stable (empfohlen für deterministisches Verhalten gegenüber :latest), und ein benanntes SQLite-Volume. Einen Docker-Healthcheck enthält die Datei bewusst nicht: Das Image basiert auf scratch und bringt weder wget noch curl mit. Den Endpunkt /health prüfen Sie vom Host aus.
Hinweis für ICMP-Monitoring: Seit Version 5.31.0 nutzt Gatus unprivilegierte Pings, icmp://-Endpunkte funktionieren daher ohne zusätzliche Capability. Nur wenn ICMP-Checks mit „permission denied“ scheitern (ältere Version oder restriktiver Host), ergänzen Sie cap_add: [NET_RAW] im Service.
| Parameter | Wert | Hinweis |
|---|---|---|
| Image | ghcr.io/twin/gatus:stable | Für feste Versionen den Tag v5.38.0 nutzen; auch twinproduction/gatus auf Docker Hub |
| Port | 8080:8080 | Dashboard, REST-API, /health und /metrics |
| Config-Volume | ./config/config.yaml:/config/config.yaml:ro | Read-only-Mount empfohlen |
| Daten-Volume | gatus-data:/data | SQLite-Persistenz; Pfad muss mit storage.path übereinstimmen |
| RAM (typisch) | ~40 MB | Richtwert, abhängig von Anzahl und Intervall der Endpunkte |
| Architektur | amd64, arm64, arm/v7 | Läuft auf Intel/AMD, Raspberry Pi und ARM-Servern |
# /opt/gatus/compose.yaml
services:
gatus:
container_name: gatus
image: ghcr.io/twin/gatus:stable
restart: unless-stopped
ports:
- "8080:8080"
volumes:
- ./config/config.yaml:/config/config.yaml:ro
- gatus-data:/data
environment:
- GATUS_CONFIG_PATH=/config/config.yaml
- GATUS_LOG_LEVEL=INFO
- SLACK_WEBHOOK_URL=${SLACK_WEBHOOK_URL}
- PAGERDUTY_KEY=${PAGERDUTY_KEY}
- SMTP_PASSWORD=${SMTP_PASSWORD}
# Nur falls ICMP-Checks mit "permission denied" scheitern:
# cap_add:
# - NET_RAW
volumes:
gatus-data:docker compose config im Projektordner zeigt die zusammengeführte Konfiguration ohne Fehler. Alle ${VAR}-Variablen aus der .env werden dabei aufgelöst und angezeigt.
Schritt 5: Container starten
Starten Sie Gatus im Hintergrund:
$ cd /opt/gatus
$ docker compose up -dDocker lädt das Image (~24 MB komprimiert) herunter, erstellt das benannte Volume gatus-data und startet den Container. Nach wenigen Sekunden läuft der Container.
# Container-Status prüfen, erwartete Ausgabe: STATUS = Up
docker compose ps
# Logs auf Fehler prüfen, keine Fehlermeldungen zu Image/Port/Volume
docker compose logs gatus
# Health-Endpunkt direkt ansprechen, erwartete Ausgabe: {"status":"UP"}
curl -s http://localhost:8080/health
# Dashboard im Browser aufrufen
# http://localhost:8080Die Logs sollten eine Zeile wie INFO Starting Gatus on port 8080 und danach die ersten Check-Ergebnisse zeigen. Erscheinen dort Meldungen wie no such file or directory für die Konfiguration, prüfen Sie den Volume-Mount und ob config/config.yaml als Datei (nicht Verzeichnis) existiert.
Schritt 6: Alerting konfigurieren und testen
Das Alerting ist vollständig über config.yaml gesteuert. Die wichtigsten Provider sind bereits im Beispiel aus Schritt 3 enthalten. Für den Produktiveinsatz gilt:
- Slack: Webhook-URL aus der Slack-App-Verwaltung in
.envalsSLACK_WEBHOOK_URLeintragen. Diefailure-threshold- undsuccess-threshold-Werte verhindern Alert-Flooding bei kurzen Ausfällen (Flapping-Prevention). - PagerDuty: Integration-Key aus dem PagerDuty-Service als
PAGERDUTY_KEYin.envsetzen. - E-Mail via Gmail: Unbedingt ein App-Passwort (nicht das Google-Account-Passwort) verwenden, da Google den Zugriff über „weniger sichere Apps“ abgeschaltet hat.
Um das Alerting ohne echten Ausfall zu testen, setzen Sie temporär eine Bedingung, die immer fehlschlägt:
conditions:
- "[STATUS] == 999" # Immer false, löst Alert ausDanach Container neu starten und auf die Benachrichtigung warten:
$ docker compose restart gatus
$ docker compose logs -f gatusNach dem Test die Bedingung zurücksetzen und Container erneut neu starten. Wichtig: Gatus lädt eine geänderte Konfiguration zwar automatisch neu, erkennt Änderungen an einer einzeln gemounteten Datei aber unter Umständen nicht (GitHub-Issue #151). Starten Sie den Container nach jeder Änderung mit docker compose restart gatus neu.
Nach dem Neustart zeigen die Logs, welche Endpunkte geprüft werden und ob Alerts ausgelöst werden (INFO Sending Slack alert o. ä.). Im Browser unter http://localhost:8080 erscheinen die Endpunkte mit ihrem aktuellen Status.
Schritt 7: Dashboard absichern und Updates einspielen
Basic-Auth für das Dashboard
Gatus bietet eingebaute HTTP-Basic-Authentifizierung. Das Passwort wird als bcrypt-Hash (Base64-kodiert) in config.yaml hinterlegt. Hash generieren:
$ docker run --rm httpd:alpine htpasswd -nbB admin 'meinPasswort' | cut -d':' -f2 | base64Den ausgegebenen String in config.yaml unter security eintragen:
security:
basic:
username: "admin"
password-bcrypt-base64: "JDJ5JDE2JGFiY2..." # Ausgabe des obigen BefehlsPrometheus-Metriken aktivieren
Wer Gatus-Daten in Prometheus mit Alertmanager oder Grafana integrieren möchte, aktiviert den Metriken-Endpunkt mit einer einzigen Zeile in config.yaml:
metrics: trueDanach sind Metriken unter http://localhost:8080/metrics abrufbar.
Updates einspielen
$ cd /opt/gatus
$ docker compose pull
$ docker compose up -dDocker lädt das neue :stable-Image und startet den Container neu. Das benannte Volume gatus-data bleibt dabei erhalten.
Die Konfiguration aus Schritt 3 und 4 übersteht das Update ohne Eingriff: /health meldet {"status":"UP"}, alle drei Endpunkte (HTTP, DNS, ICMP) laufen weiter, und die Messwerte aus der Zeit vor dem Update bleiben im Volume erhalten. Mit aktivierter Basic-Auth beantwortet die API Anfragen ohne und mit falschem Passwort mit 401, mit richtigem Passwort mit 200. Ein Platzhalter wie ihr-pagerduty-integration-key führt übrigens nur zu einer Warnung im Log (integration-key must have exactly 32 characters), der Anbieter wird dann ignoriert.
Nach dem Update zeigt docker compose ps den Status Up, und curl -s http://localhost:8080/health liefert {"status":"UP"}. docker image ls ghcr.io/twin/gatus zeigt das neue Image-Datum.
Troubleshooting / Typische Fehler
- „permission denied“ bei ICMP-Checks
Ab Version 5.31.0 selten; betroffen sind ältere Versionen oder Hosts, die unprivilegierte Pings sperren. Lösung:
cap_add: [NET_RAW]imgatus-Service incompose.yamleintragen und Container neu starten.- Gatus startet nicht, Logs zeigen „no such file or directory“ für config.yaml
Docker hat beim ersten Mount ein Verzeichnis statt einer Datei angelegt. Lösung:
docker compose down, das fehlerhafte Verzeichnis entfernen, Datei mittouchneu erstellen und Container neu starten.- SQLite-Daten gehen nach Neustart verloren
Das Volume
gatus-data:/datafehlt incompose.yamloderstorage.pathinconfig.yamlzeigt auf einen anderen Pfad als/data/gatus.db. Volume-Mount und Pfad müssen identisch sein.- Endpunkt dauerhaft rot mit „invalid condition“
Bedingungssyntax prüfen,
[STATUS] == 200braucht Leerzeichen um==.- Gmail-SMTP schlägt fehl mit „Username and Password not accepted“
Google blockiert reguläre Account-Passwörter. Ein App-Passwort in der Google-Konto-Verwaltung unter „Sicherheit → App-Passwörter“ erstellen und in
.envalsSMTP_PASSWORDeintragen.- „permission denied“ beim Lesen von config.yaml auf Linux mit SELinux
Volume-Mount um das
:z-Flag erweitern:./config/config.yaml:/config/config.yaml:ro,z.- Konfigurationsänderungen haben keine Wirkung
Bei einer einzeln gemounteten Datei erkennt Gatus Änderungen nicht immer. Nach jeder Änderung an
config.yamlistdocker compose restart gatuserforderlich.
Häufige Fragen
Brauche ich zwingend eine Datenbank?
Nein. Ohne storage-Block in config.yaml speichert Gatus alle Daten im Arbeitsspeicher. Das reicht für einfache Setups, aber nach einem Container-Neustart ist die gesamte Uptime-Historie weg. SQLite ist die empfohlene leichtgewichtige Alternative, ein einfaches benanntes Volume genügt, keine separate Datenbank-Infrastruktur nötig.
Kann ich mehrere Konfigurationsdateien nutzen?
Ja. Wenn GATUS_CONFIG_PATH auf ein Verzeichnis zeigt (z. B. /config), lädt Gatus automatisch alle *.yaml- und *.yml-Dateien und mergt sie. Arrays wie endpoints werden dabei angehängt, nicht überschrieben. Das ist ideal für GitOps-Workflows, bei denen Endpunkte pro Team oder Umgebung in separaten Dateien gepflegt werden.
Wie definiere ich Wartungsfenster, um Fehlalarme zu vermeiden?
Global über den Block maintenance mit start (hh:mm), duration, timezone (z. B. Europe/Berlin: Standard UTC) und optional every (Wochentage). Für einzelne Endpunkte nutzen Sie die Liste maintenance-windows im Endpunkt-Block. Während des Fensters löst Gatus keine Alerts aus, auch wenn Checks fehlschlagen.
Wie viele Endpunkte kann Gatus gleichzeitig überwachen?
Das ist über den globalen Parameter concurrency (Standard: 3 parallele Checks) konfigurierbar. Bei vielen Endpunkten diesen Wert erhöhen. 0 hebt die Begrenzung auf; bei sehr hoher Parallelität werden [RESPONSE_TIME]-Werte ungenauer.
Wie unterscheidet sich Gatus von Uptime Kuma?
Uptime Kuma bietet eine grafische Oberfläche zur Konfiguration, Gatus arbeitet ausschließlich per YAML, was es besser für GitOps und automatisierte Deployments geeignet macht. Gatus unterstützt zudem mehr Protokolle (DNS, gRPC, SSH) und hat einen deutlich geringeren RAM-Verbrauch. Wer die Konfiguration per Oberfläche bevorzugt, nutzt Uptime Kuma.
Fazit
Gatus passt, wenn Sie Monitoring-Konfigurationen versionieren, per GitOps ausrollen und mit wenig Ressourcen betreiben möchten. Der Preis des YAML-Ansatzes: Jede Änderung erfolgt in der Datei, nicht im Browser. Dafür vereint ein Container Statusseite und internes Monitoring. Für umfangreichere Monitoring-Stacks mit Metriken und Dashboards lohnt sich die Integration mit cAdvisor und Prometheus: Gatus liefert dabei den /metrics-Endpunkt für den Prometheus-Scraper.
Weiterführende Anleitungen und Quellen
- Beszel Server Monitoring mit Docker einrichten: GUI-basiertes Monitoring als Alternative
- Prometheus Alerts an Telegram und Discord senden: Alertmanager für komplexere Alert-Routing-Logik
- cAdvisor mit Prometheus: Docker-Container-Metriken sammeln und in Grafana visualisieren
- Docker Compose absichern: Secrets, Healthchecks, Non-Root: Best Practices für den Produktivbetrieb
Offizielle Dokumentation und Quellcode: GitHub: TwiN/gatus · GHCR: ghcr.io/twin/gatus · Docker Hub: twinproduction/gatus


