Du öffnest morgens deine Website und bekommst einen 502-Fehler. Seit wann ist sie nicht erreichbar? Und war es nur ein kurzer Aussetzer oder lief die Seite die ganze Nacht nicht? Mit Uptime Kuma kannst du solche Ausfälle automatisch erkennen und im Verlauf nachsehen, seit wann die Prüfungen fehlschlagen.
Was ist Uptime Kuma?
Uptime Kuma ist ein Open-Source-Projekt von Louis Lam, das du auf einem eigenen Server betreibst. Für jeden Dienst legst du einen Monitor an und stellst ein, wie oft Kuma prüfen soll. Im Dashboard siehst du, welche Dienste gerade erreichbar sind, wie sich ihre Antwortzeiten entwickeln und wann Prüfungen fehlgeschlagen sind. Für Benachrichtigungen kannst du unter anderem E-Mail, Telegram, Discord oder Gotify einrichten.
Was sich zu überwachen lohnt
- Website oder API: Ein HTTPS-Check prüft, ob der Endpunkt wie erwartet antwortet. Mit einem Keyword-Check kannst du zusätzlich nach einem Text suchen, der auf der richtigen Seite vorkommen muss. Das hilft, wenn eine Fehlerseite trotzdem HTTP 200 zurückgibt.
- Dienst im Heimnetz: Ein TCP-Check prüft, ob sich eine Verbindung zum Port aufbauen lässt. Für eine Datenbank sagt dir das, ob der Port erreichbar ist. Ob eine Anmeldung oder Abfrage funktioniert, prüft der TCP-Check allein nicht.
- Backup oder Cronjob: Bei einem Push-Monitor meldet sich das Skript selbst. Bleibt die Meldung länger als erwartet aus, kann Kuma Alarm schlagen. So fällt auch ein Job auf, der gar nicht erst gestartet ist.
Push-Monitore für Backups und geplante Jobs
Bei einem HTTPS-Monitor ruft Kuma den Dienst auf. Bei einem Push-Monitor läuft es umgekehrt: Dein Skript ruft die von Kuma erzeugte URL auf und meldet damit, dass der Job gelaufen ist. Die Benachrichtigung an dich stellst du separat ein, zum Beispiel per E-Mail oder Telegram.
Für meine Restic-Backups meldet das Skript den Erfolg an Uptime Kuma. Wichtig ist der Zeitpunkt: Die Erfolgsmeldung gehört ans Ende des Jobs, nachdem Restic erfolgreich beendet wurde. Startet der Job gar nicht oder kommt die Meldung wegen eines Netzwerkproblems nicht an, erkennt Kuma nach Ablauf des erwarteten Intervalls, dass die Rückmeldung fehlt.
Ein Fehler lässt sich auch direkt mit status=down melden. Für die Erfolgsmeldung verwendest du status=up. Bei einem täglichen Job sollte das Intervall in Kuma etwas länger als 24 Stunden sein, wenn die Laufzeit schwankt. Behandle die Push-URL wie ein Passwort. Wer den Token kennt, kann den Status des Monitors melden. Die Parameter stehen in der Projektdokumentation zur Push-Schnittstelle.
Server prüfen: vom Ping bis zur Anwendung
Ein Ping zeigt dir, ob der Host aus Sicht von Kuma auf ICMP antwortet. Der Webserver kann dabei längst ausgefallen sein. Ein TCP-Check geht einen Schritt weiter und versucht, eine Verbindung zum Port aufzubauen. Welcher Check passt, hängt davon ab, was ausfallen kann und was du davon mitbekommen willst.
Für Microsoft SQL Server, PostgreSQL, MySQL/MariaDB, MongoDB und Redis gibt es eigene Monitortypen. Wenn dich interessiert, ob Kuma sich tatsächlich mit der Datenbank verbinden kann, ist ein passender Datenbankmonitor aussagekräftiger als ein offener TCP-Port. Ob die Anwendung mit ihrem eigenen Konto auf die benötigten Daten zugreifen kann, prüfst du am besten zusätzlich über einen geeigneten Health-Endpunkt.
Ähnlich ist es bei Docker: Kuma kann über die Docker-Schnittstelle prüfen, ob ein Container läuft. Ob die Webanwendung darin eine brauchbare Antwort liefert, prüfst du separat mit HTTPS oder einer JSON-Abfrage. Wie du den Docker-Monitor einrichtest, steht im Projektwiki.
Für Gameserver gibt es Steam- und GameDig-Monitore. Sie fragen unterstützte Spielserver über ihr Abfrageprotokoll ab. Für andere Dienste gibt es unter anderem DNS-, MQTT- und gRPC-Monitore. So kannst du beispielsweise einen erwarteten DNS-Eintrag oder eine bestimmte Antwort eines gRPC-Dienstes prüfen. Einen Überblick findest du im Projekt-Repository.
Von wo aus wird geprüft?
Für interne Dienste wie ein NAS ist ein Monitor im Heimnetz sinnvoll. Für eine öffentliche Website lohnt sich ein Check von außerhalb. Läuft Kuma auf demselben Host wie die Website, fallen bei einem Host-Ausfall beide gleichzeitig aus. Ähnlich ist es bei einem Internetausfall zu Hause: Ein Kuma im selben Netz kann dann womöglich keine Meldung mehr verschicken. Ein Monitor auf einem unabhängigen Server kann die öffentliche Erreichbarkeit weiterhin prüfen.
Wie schnell du einen Ausfall bemerkst, hängt vom Prüfintervall, den eingestellten Wiederholungen und dem Benachrichtigungskanal ab. Eine kurze Unterbrechung zwischen zwei Prüfungen kann unbemerkt bleiben. Der Verlauf hilft dir, die Fehlersuche zeitlich einzugrenzen. Für die Ursache brauchst du je nach Problem zusätzlich Logs, Metriken oder einen Blick in die Anwendung.
Dashboard und Statusseite
Das Dashboard ist für dich als Betreiber gedacht. Über eine Statusseite kannst du ausgewählte Dienste öffentlich anzeigen. Wer gerade auf deine Website oder API angewiesen ist, kann dort nachsehen, ob eine Störung bekannt ist.
Uptime Kuma mit Docker Compose starten
Du brauchst einen Host mit Docker und dem Compose-Plugin. Lege dort einen Ordner für Uptime Kuma an und speichere diese Datei als compose.yaml. Das Beispiel basiert auf der Compose-Datei des Projekts.
services:
uptime-kuma:
image: louislam/uptime-kuma:2
restart: unless-stopped
ports:
- "127.0.0.1:3001:3001"
volumes:
- ./data:/app/dataStarte den Container im Verzeichnis der compose.yaml und prüfe anschließend seinen Status.
docker compose up -d
docker compose psSobald der Container läuft, erreichst du die Ersteinrichtung auf dem Docker-Host unter http://localhost:3001. Die Portbindung an 127.0.0.1 hält die Oberfläche lokal. Wenn Docker auf einem entfernten Server läuft, kannst du für die Einrichtung einen SSH-Tunnel nutzen.
Die Konfiguration und der Verlauf liegen im lokalen Ordner ./data neben der Compose-Datei. So bleiben sie erhalten, wenn du den Container neu erstellst. Nutze dafür ein lokales Dateisystem. NFS wird laut Installationsanleitung nicht unterstützt.
Mit einem Monitor anfangen
Wenn du Kuma erst ausprobieren möchtest, gibt es eine offizielle Live-Demo. Lege zuerst einen HTTPS-Monitor für einen wichtigen Dienst an und verbinde ihn mit deinem Benachrichtigungskanal.
Ob die Meldung wirklich ankommt, kannst du mit einem separaten Testdienst prüfen. Lass Kuma den Dienst zunächst als erreichbar anzeigen, stoppe ihn kurz und warte auf den Alarm. Starte ihn dann wieder und prüfe, ob der Monitor zurück auf „Up“ wechselt. So weißt du vor dem ersten echten Ausfall, dass die Überwachung bis zur Benachrichtigung funktioniert.
