Gatus mit Docker installieren: Entwicklerorientiertes Status-Dashboard für HTTP, DNS und ICMP

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

1. Docker Engine 20.10+ und Docker Compose v2 (Befehl: docker compose, nicht docker-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.
2. Mindestens 50 MB RAM und 100 MB freier Speicher (ohne Datenbank); für die PostgreSQL-Variante zusätzlich ~256 MB RAM.
3. Einen Texteditor (nano, VS Code o. ä.) für config.yaml und .env.
4. curl oder wget zum Testen der Endpunkte sowie einen Browser für das Dashboard.
5. Optional: Slack-Webhook-URL, PagerDuty Integration-Key oder SMTP-Zugangsdaten für Alerting-Tests.
6. 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/gatus

Die resultierende Verzeichnisstruktur sieht so aus:

/opt/gatus/
├── compose.yaml
├── .env
└── config/
    └── config.yaml

Verifizieren: ls -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-passwort

Danach unbedingt .env zur .gitignore hinzufügen, damit Secrets nicht ins Repository gelangen:

echo ".env" >> /opt/gatus/.gitignore

Verifizieren: cat /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"

Verifizieren: 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.

# /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:

Verifizieren: 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 -d

Docker 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.

Verifizieren:

# 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:8080

Die 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:

1. Slack: Webhook-URL aus der Slack-App-Verwaltung in .env als SLACK_WEBHOOK_URL eintragen. Die failure-threshold- und success-threshold-Werte verhindern Alert-Flooding bei kurzen Ausfällen (Flapping-Prevention).
2. PagerDuty: Integration-Key aus dem PagerDuty-Service als PAGERDUTY_KEY in .env setzen.
3. 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 aus

Danach Container neu starten und auf die Benachrichtigung warten:

docker compose restart gatus
docker compose logs -f gatus

Nach 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.

Verifizieren: 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 | base64

Den ausgegebenen String in config.yaml unter security eintragen:

security:
  basic:
    username: "admin"
    password-bcrypt-base64: "JDJ5JDE2JGFiY2..."   # Ausgabe des obigen Befehls

Prometheus-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: true

Danach sind Metriken unter http://localhost:8080/metrics abrufbar.

Updates einspielen

cd /opt/gatus
docker compose pull
docker compose up -d

Docker lädt das neue :stable-Image und startet den Container neu. Das benannte Volume gatus-data bleibt dabei erhalten.

Verifizieren: 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

1. „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] im gatus-Service in compose.yaml eintragen und Container neu starten.
2. 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 mit touch neu erstellen und Container neu starten.
3. SQLite-Daten gehen nach Neustart verloren: Das Volume gatus-data:/data fehlt in compose.yaml oder storage.path in config.yaml zeigt auf einen anderen Pfad als /data/gatus.db. Volume-Mount und Pfad müssen identisch sein.
4. Endpunkt dauerhaft rot mit „invalid condition“: Bedingungssyntax prüfen, [STATUS] == 200 braucht Leerzeichen um ==.
5. 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 .env als SMTP_PASSWORD eintragen.
6. „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.
7. Konfigurationsänderungen haben keine Wirkung: Bei einer einzeln gemounteten Datei erkennt Gatus Änderungen nicht immer. Nach jeder Änderung an config.yaml ist docker compose restart gatus erforderlich.

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

1. Beszel Server Monitoring mit Docker einrichten – GUI-basiertes Monitoring als Alternative
2. Prometheus Alerts an Telegram und Discord senden – Alertmanager für komplexere Alert-Routing-Logik
3. cAdvisor mit Prometheus – Docker-Container-Metriken sammeln und in Grafana visualisieren
4. 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

Passende Anleitungen auf S-EDV

1. Prometheus node_exporter nativ installieren und als systemd-Dienst betreiben
2. Docker und Docker Compose auf Linux installieren (Ubuntu/Debian)