Uptime Kuma: merken, wenn das Homelab ausfällt

Das klassische Überwachungssystem im Homelab ist ein Familienmitglied, das sagt: „Das Internet geht wieder nicht.“ Es funktioniert, ist aber langsam, laut und hat keinen Verlauf. Uptime Kuma sagt dir Bescheid, bevor jemand fragt, und liefert gleich eine Grafik dazu.

Kurz gesagt

Uptime Kuma ist ein selbst gehostetes Überwachungswerkzeug mit Weboberfläche und MIT-Lizenz. Es prüft Webseiten, Ports, Ping-Ziele, DNS-Einträge, Docker-Container und geplante Jobs, auf Wunsch alle 20 Sekunden, und meldet sich über mehr als 90 Dienste wie Telegram, Discord, ntfy oder E-Mail [1][10]. Die Einrichtung dauert Minuten. Nützlich wird es durch vier Entscheidungen: Betreibe es an einem Ort, der nicht gemeinsam mit den überwachten Geräten ausfällt, nutze Wiederholungen, damit ein einzelner Aussetzer dich nicht weckt, richte mindestens einen Alarmweg ein, der ohne dein Homelab funktioniert, und sichere den Datenordner. Unsere Einschätzung: Ein Überwachungswerkzeug, das mit dem Überwachten stirbt, schweigt sehr höflich.

So funktioniert’s

1. Was es prüft. Die README nennt Überwachung für HTTP(S), TCP, HTTP(S)-Schlüsselwort, HTTP(S)-JSON-Abfrage, WebSocket, Ping, DNS-Eintrag, Push, Steam-Spieleserver und Docker-Container. Dazu kommen mehrere Statusseiten, Zertifikatsinformationen, Proxy-Unterstützung und Zwei-Faktor-Anmeldung [1]. Alles stellst du im Browser ein, und die Daten liegen in einem einzigen Ordner data, im Container unter /app/data eingehängt [1][2]. Den Port (standardmäßig 3001) und das Datenverzeichnis kannst du über Umgebungsvariablen ändern [15].
2. Versionen und Tags am 24. Okt. 2026. Version 2 ist die aktuelle Hauptlinie. Das neueste Release, das wir gefunden haben, ist 2.5.7 vom 23. Okt. 2026, und der Tag 2.5.7 existiert auf Docker Hub [5][6]. Dieses Release behebt einen Fehler, bei dem der TCP-Port-Monitor Wiederholungen mit SSL/STARTTLS ignorierte, und hebt die Docker-Images auf Node.js 22.23.4 an, das laut Hinweisen ein geleaktes CA-Zertifikat ablehnt [6]. Die Tag-Übersicht des Projekts nennt latest veraltet und sagt, dass der Tag weiter auf Version 1 zeigt. Empfohlen wird 2 für das jeweils neueste 2.x-Release, und 2.x.x pinnt eine exakte Version [4]. Wir pinnen im Beispiel unten die genaue Version, damit ein Update eine Entscheidung ist und keine Überraschung. Wenn du lieber der Projektempfehlung folgst: louislam/uptime-kuma:2 steht auch in der eigenen Compose-Datei des Projekts [1]. Die -slim-Varianten sind kleiner, und bei den Rootless-Images warnt das Projekt, vor allem beim Umstieg von Version 1 [4].
3. Installation. Die README zeigt eine Compose-Datei und einen einzelnen docker run-Befehl. Der Dienst lauscht auf Port 3001 auf allen Schnittstellen, und die README nennt -p 127.0.0.1:3001:3001, um ihn auf den Rechner selbst zu beschränken [1]. Lege die Daten auf eine lokale Platte oder ein lokales Volume. Dateisysteme wie NFS werden nicht unterstützt, weil SQLite verlässliches Dateisperren braucht [1][2]. Beim ersten Aufruf legst du das Admin-Konto an, und in Version 2 fragt der erste Bildschirm zusätzlich nach der Datenbank. SQLite ist die einfache Wahl für ein kleines Setup [16]. Leg das Konto sofort an und schalte unter Einstellungen, Sicherheit die Zwei-Faktor-Anmeldung ein [16]. Solange kein Konto existiert, könnte jeder, der die Adresse zuerst erreicht, sie für sich beanspruchen.
4. Wo es laufen sollte. Ein Monitor kann seinen eigenen Ausfall nicht melden [16]. Läuft Uptime Kuma auf demselben Gerät, am selben Switch oder am selben Stromkreis wie das Überwachte, bringt ein Stromausfall oder eine tote Leitung genau das Werkzeug zum Schweigen, das dir Bescheid sagen sollte. Unsere Einschätzung: Nimm einen kleinen Rechner an einem anderen Stromkreis, einen günstigen VPS oder ein Gerät bei Freunden und lass es dein Zuhause über das Internet beobachten. Denk auch an die Gegenrichtung: Hängt der Alarmweg selbst von deinem Homelab ab (etwa ein selbst gehosteter Chatserver), stirbt der Alarm mit dem Ausfall. Wähle einen Kanal, der anderswo lebt, etwa E-Mail über einen externen Anbieter oder einen gehosteten Messenger [10]. Und beachte, was eine USV hier leistet: Sie verschafft deinem Homelab Minuten, sagt dir aber nicht, dass der Strom weg ist. Das muss etwas von außen tun. Das Gerät erklären wir in „USV – unterbrechungsfreie Stromversorgung“ (verlinkt unter „Passt dazu“).
5. Monitortypen im Homelab. Nimm Ping für Router, Switch und Hypervisor-Hosts. Nimm TCP-Port-Monitore für Dienste, die keine Webseite sind, etwa SSH. Nimm HTTP(S)-Monitore für Weboberflächen und deinen Reverse Proxy, bei HTTPS-Zielen mit eingeschalteter Benachrichtigung vor Zertifikatsablauf [16]. Der DNS-Monitor prüft, ob ein Name aufgelöst wird, und passt zum Resolver, den du zu Hause betreibst (siehe „DNS / Namensauflösung“ unter „Passt dazu“). Der Docker-Container-Monitor braucht den Docker-Socket im Uptime-Kuma-Container. Das Projekt warnt, dass Uptime Kuma damit volle Kontrolle über den Docker-Daemon des Hosts bekommt, dass sich eine Kompromittierung ausbreiten kann und dass du Uptime Kuma bei diesem Monitortyp nicht ins Internet stellen solltest [14]. Unsere Einschätzung: Lass diesen Typ weg, wenn du ihn nicht wirklich brauchst, und überwache Container lieber über ihre Ports.
6. Alarme ohne Lärm. Lege einen Kanal unter Einstellungen, Benachrichtigungen an, drücke auf „Test“ und setze den Haken, damit er für neue Monitore standardmäßig aktiv ist [16]. Zu den eingebauten Anbietern gehören Telegram, Discord, Gotify, Slack, Pushover, E-Mail (SMTP), ntfy, Matrix, Signal und ein allgemeiner Webhook [1][10]. Über Apprise kommen weitere Dienste dazu [9]. Seit Version 2 steht die Zahl der Wiederholungen bei neu angelegten Monitoren standardmäßig auf 0, eine Änderung, die das Projekt gegen Verwirrung vorgenommen hat [7]. Heißt: Ein einziger fehlgeschlagener Test löst Alarm aus. Setze für die meisten Homelab-Dienste ein paar Wiederholungen und ein Wiederholungsintervall. Mit 60 Sekunden Intervall, drei Wiederholungen und 60 Sekunden Wiederholungsintervall meldet sich ein echter Ausfall nach etwa drei bis vier Minuten, und ein einmaliger Netzwerkaussetzer bleibt still. Die Zahlen sind unser Beispiel, stimme sie auf deine Geduld ab. Ein Wartungsfenster schaltet Benachrichtigungen für einen von dir festgelegten Zeitraum ab und zeigt auf den gewählten Statusseiten eine Meldung [13]. Leg es an, bevor du den Hypervisor neu startest, nicht danach.
7. Push-Monitore: Jobs überwachen, nicht nur Dienste. Ein Push-Monitor arbeitet andersherum. Dein Skript ruft eine URL auf, und Uptime Kuma schlägt Alarm, wenn der Aufruf nicht innerhalb des Intervalls eintrifft [16]. Der Endpunkt lautet /api/push/<Token> mit den optionalen Parametern status (up oder down, Standard up), msg (kurze Nachricht) und ping (Zahl in Millisekunden). Das Token im Pfad ist die einzige Authentifizierung [11]. Die API-Seite des Projekts fügt eine Warnung hinzu: Die Schnittstelle ist vor allem für die Anwendung selbst gedacht, und zwischen Versionen können sich Dinge ohne Vorwarnung ändern, teste sie also nach Updates [11]. Das ist die saubere Antwort auf das älteste Backup-Problem: Ein fehlgeschlagener Backup-Job beschwert sich nicht, er bleibt einfach still. Lass das Skript nur bei Erfolg melden, und die Stille wird dein Alarm. Unsere Einschätzung: Setze das Intervall etwas länger als den Zeitplan.
8. Reverse Proxy und Statusseite. Uptime Kuma spricht mit dem Browser über WebSockets, ein vorgeschalteter Proxy braucht also die Header Upgrade und Connection. Caddy erledigt das von allein [16]. Das Projekt stellt außerdem klar, dass Uptime Kuma keinen Unterpfad wie /uptimekuma unterstützt, gib ihm also eine eigene (Sub-)Domain [8][16]. Ist es nur über den Proxy erreichbar, kannst du in den Proxy-Einstellungen „Trust Proxy“ einschalten, damit die Logs die echte Client-Adresse zeigen [8]. Statusseiten sind für die Öffentlichkeit gedacht, halten Ergebnisse fünf Minuten im Cache und aktualisieren sich alle fünf Minuten, hinken also dem Dashboard hinterher [12]. Eine Statusseite für Familie und Freunde ist eine nette Geste. Unsere Einschätzung: Veröffentlichst du eine, schütze die Admin-Seite mit Zwei-Faktor-Anmeldung und erwäge, das Dashboard nur aus dem LAN oder per VPN erreichbar zu machen. Den allgemeinen Aufbau erklärt unser Reverse-Proxy-Guide (verlinkt unter „Passt dazu“).
9. Backup und Update. In Version 2 wurde die alte JSON-Sicherung samt Wiederherstellung entfernt. Laut Migrationsanleitung des Projekts ist die Sicherung des Verzeichnisses data derzeit die einzige unterstützte Methode [7]. Eine Anleitung von HyperDC hält den Container für die Kopie an, damit die Datenbankdateien konsistent sind [16]. Ein Update unter Docker heißt: neues Image ziehen und den Container mit demselben Volume neu erstellen. Mit Compose sind das docker compose pull und docker compose up -d --force-recreate [3]. Eine große Migration wie von Version 1 auf 2 schreibt die Heartbeat-Tabelle um. Das Projekt nennt rund sieben Minuten für 20 Monitore mit 90 Tagen Daten und Stunden auf langsamer Hardware. Unterbrich sie nicht, und spiel bei einem Abbruch das Backup zurück [7]. Wohin die Kopie gehört, erklärt unser restic-Guide (verlinkt unter „Passt dazu“).

Ein Homelab-Beispiel

Das ist eine Skizze für dein eigenes Setup, kein Bericht über unseres. Namen, Adressen und Token sind Beispiele.

Angenommen, du hast einen kleinen Server, der nicht zu den überwachten Geräten gehört, Docker mit dem Compose-Plugin und einen Reverse Proxy, der status.example.net per HTTPS ausliefert. Lege /opt/uptime-kuma/compose.yaml an. Sie folgt der Compose-Datei des Projekts, mit exaktem Tag statt :2 und einem Port nur auf Loopback [1][5]:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2.5.7
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      - "127.0.0.1:3001:3001"

Starte mit docker compose up -d und prüfe docker compose logs --tail 30. Der Proxy-Block für Caddy ist das Beispiel des Projekts, status.example.net { reverse_proxy 127.0.0.1:3001 } [8]. Öffne die Seite sofort, lege das Admin-Konto an und schalte die Zwei-Faktor-Anmeldung ein.

Lege einen ersten Satz Monitore an. Die Ziele sind Beispiele:

Nimm für die ersten vier 60 Sekunden Intervall und ein paar Wiederholungen. Beim Backup-Monitor kopierst du die Push-URL und hängst sie so an den Job, dass sie nur bei erfolgreichem Backup feuert:

restic -r /mnt/backup/restic-lokal backup /srv/daten \
  && curl -fsS -m 10 "https://status.example.net/api/push/BEISPIELTOKEN?status=up&msg=OK" > /dev/null

Stelle das Heartbeat-Intervall des Push-Monitors bei einem nächtlichen Job auf etwa 26 Stunden (93.600 Sekunden), damit ein verspäteter Lauf keinen Alarm auslöst, eine verpasste Nacht aber schon. Willst du außerdem erfahren, wann das Homelab selbst verstummt, betreibe eine zweite kleine Instanz an einem anderen Ort und lass einen Cronjob im Homelab alle paar Minuten deren Push-URL aufrufen. Bleiben die Aufrufe aus, alarmiert dich die Instanz von außen.

Sicherung, mit kurz angehaltenem Container:

docker compose stop
tar -czf /srv/backup/uptime-kuma-$(date +%F).tar.gz -C /opt/uptime-kuma compose.yaml data
docker compose start

Zum Aktualisieren liest du die Release-Hinweise, sicherst, änderst den Tag in der compose.yaml und führst docker compose pull sowie docker compose up -d --force-recreate aus [3]. Schau einmal in die Logs.

Prüfliste

• Lege fest, wo Uptime Kuma läuft, und prüfe, dass es sich weder Gerät noch Switch noch Stromkreis mit den überwachten Diensten teilt.
• Lege das Admin-Konto direkt nach dem ersten Start an und aktiviere die Zwei-Faktor-Anmeldung.
• Pinne einen genauen Image-Tag wie louislam/uptime-kuma:2.5.7, meide latest und lies vor jeder Änderung die Release-Hinweise.
• Halte den Ordner data auf einer lokalen Platte, nie auf NFS.
• Veröffentliche den Port auf 127.0.0.1 und stelle einen Reverse Proxy mit HTTPS davor. Prüfe, dass WebSockets funktionieren.
• Richte mindestens einen Benachrichtigungskanal ein, der nicht von deinem Homelab abhängt, und drücke auf „Test“.
• Setze bei jedem Monitor Wiederholungen und ein Wiederholungsintervall, denn neue Monitore starten in Version 2 mit null Wiederholungen.
• Lege Push-Monitore für Backups und andere geplante Jobs an und lass das Skript nur bei Erfolg melden.
• Lege vor geplanten Arbeiten ein Wartungsfenster an.
• Sichere das Verzeichnis data regelmäßig, spiele es einmal auf einem anderen Rechner zurück und notiere das Datum.
• Meide den Docker-Container-Monitor, solange du nicht akzeptierst, dass er den Docker-Socket freigibt.