Uptime Kuma einrichten: Docker Compose, ntfy und Backup

60 Sekunden. So lange dauert es bei Uptime Kuma von einer Prüfung bis zur nächsten, und in dieser Zeit fragt das Werkzeug bei jedem deiner Dienste nach, ob er noch antwortet. Ohne so einen Wächter fällt ein Ausfall erst auf, wenn jemand den Dienst benutzen will. Im Homelab merkt den Ausfall meistens zuerst, wer den Dienst benutzt, und erst danach der, der ihn betreibt.

Diese Anleitung beginnt bei einem frischen Debian-Server, auf dem noch nichts läuft. Am Ende ist Docker installiert, Uptime Kuma 2 läuft per Docker Compose mit SQLite, prüft seinen ersten Monitor und schickt Meldungen an ein ntfy-Topic, das du selbst mitlesen kannst. Dazu ein Backup in vier Befehlen.

Was Uptime Kuma macht

Uptime Kuma ist eine Web-App, die andere Dienste in festen Abständen abfragt. Jede dieser Abfragen heißt Monitor. Ein Monitor ruft zum Beispiel eine Webseite auf und prüft, ob sie mit einem Statuscode zwischen 200 und 299 antwortet, also mit „alles in Ordnung“. Andere Monitore pingen ein Gerät, prüfen einen offenen Port oder einen DNS-Eintrag. Jede einzelne Prüfung heißt Heartbeat, Herzschlag, und so sieht die Oberfläche auch aus: eine Reihe kleiner Balken, grün für „antwortet“, rot für „antwortet nicht“.

Fällt etwas aus, schickt Uptime Kuma eine Nachricht. Das README nennt Telegram, Discord, Gotify, Slack, Pushover und E-Mail und mehr als 90 weitere Wege. Ich nehme ntfy, weil es ohne Konto auskommt: Uptime Kuma schickt seine Meldungen an ein Stichwort, das sogenannte Topic, auf dem öffentlichen Server ntfy.sh. Wer dieses Topic kennt, liest mit, ob per Befehl im Terminal, im Browser oder in der ntfy-App.

Das Projekt von Louis Lam steht unter der MIT-Lizenz. Aktuell ist Version 2.5.9 vom 31-10-2026. Im Wiki steht schon eine Migrationsseite für Version 3, die als Beta läuft und laut derselben Seite die Datenbank so umbaut, dass kein Weg zurück zu Version 2 führt. Daraus folgt die wichtigste Zeile der Compose-Datei, das Image-Tag 2: Es bekommt jede Korrektur der 2er-Reihe und springt nie von selbst auf 3. Den Sprung würde ich erst machen, wenn 3.0 stabil ist und ein paar Wochen hinter sich hat.

Was du brauchst

• Einen frischen Debian-Server, auf den du per SSH kommst, mit einem Benutzer, der sudo darf. Prüfen mit sudo whoami: Nach deinem Passwort antwortet der Server mit root.
• Seine IP-Adresse im Heimnetz. hostname -I zeigt sie an, die erste Adresse ist die richtige.
• Internet auf dem Server. Das prüft der erste Befehl in Schritt 1 gleich mit: Lädt apt update Paketlisten, steht die Verbindung.
• Ein selbst gewähltes, langes Passwort für das Admin-Konto von Uptime Kuma, am besten aus deinem Passwort-Manager.

Schritt 1: Docker installieren

Docker ist das Werkzeug, das Uptime Kuma in einem Container startet, einer abgeschlossenen Kiste mit allem, was die App braucht. Die offizielle Docker-Doku installiert Docker Engine und das Compose-Plugin über die Paketquelle von Docker selbst, und die folgenden Befehle stammen aus ihrer Anleitung für Debian, ergänzt nur um ein -y. Der erste Block trägt die Paketquelle samt Schlüssel ein, mit dem apt die Pakete auf Echtheit prüft:

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt update

Den ganzen Block auf einmal einfügen, die Zeilen zwischen <<EOF und EOF gehören zusammen und landen als Datei in /etc/apt/sources.list.d/. Das -y beantwortet die Rückfrage von apt gleich mit Ja. Geklappt hat es, wenn das letzte apt update eine Zeile mit download.docker.com zeigt. Jetzt die Pakete selbst:

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Die Docker-Doku prüft die Installation mit einem winzigen Test-Image, das nur einen Gruß ausgibt und sich wieder beendet. Ich filtere den Gruß heraus, der Rest der Ausgabe ist Erklärtext:

sudo docker run --rm hello-world | grep 'Hello from Docker'

Hello from Docker!

Das ist der erste Container auf deinem Server, und er hat genau einen Satz gesagt. Mehr will man an dieser Stelle nicht hören. Das --rm räumt ihn danach gleich wieder weg. In dieser Anleitung steht vor jedem docker ein sudo: Docker verlangt Root-Rechte, und so musst du dich nicht ab- und wieder anmelden, wie es der Umweg über die Gruppe docker verlangen würde.

Schritt 2: Ordner und Compose-Datei anlegen

Eine Compose-Datei ist der Bauplan, nach dem Docker den Container startet: welches Image, welcher Port, wo die Daten liegen. Für Uptime Kuma ist sie zehn Zeilen lang. Ordner anlegen, hineinwechseln, Datei im Editor nano öffnen:

mkdir -p ~/uptime-kuma
cd ~/uptime-kuma
nano compose.yaml

In nano den folgenden Inhalt einfügen, im Terminal klappt das meist mit Strg+Umschalt+V oder einem Rechtsklick. Speichern mit Strg+O und Enter, schließen mit Strg+X.

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    environment:
      UPTIME_KUMA_DB_TYPE: sqlite
    volumes:
      - ./data:/app/data
    ports:
      - "3001:3001"

Bis auf die zwei Zeilen unter environment ist das die offizielle compose.yaml aus dem Repository. Vier Stellen tragen das Ganze:

• image: louislam/uptime-kuma:2: das Tag aus dem Abschnitt oben. Finger weg von latest, das zeigt laut Wiki noch immer auf das alte Uptime Kuma 1.
• UPTIME_KUMA_DB_TYPE: sqlite: Uptime Kuma 2 fragt beim ersten Aufruf sonst im Browser, wo es seine Daten speichern soll. Diese Umgebungsvariable, im Wiki seit Version 2.0.0 dokumentiert, beantwortet die Frage vorab. SQLite ist eine Datenbank in einer einzigen Datei, für ein Homelab mit ein paar Dutzend Monitoren genau richtig und beim Sichern unschlagbar einfach. Mir ist die Wahl im Bauplan lieber als in einem Klick, den man nach einem Neuaufbau vergessen kann. Sie gilt allerdings auf Dauer: Einen direkten Wechsel von SQLite zu MariaDB unterstützt Uptime Kuma laut Wiki nicht.
• ./data:/app/data: Alles, was Uptime Kuma sich merkt, landet im Container unter /app/data. Diese Zeile legt den Ordner nach draußen, nach ~/uptime-kuma/data. Ohne sie wären Monitore und Verlauf weg, sobald der Container neu gebaut wird, und mit ihr ist das Backup später ein einziger Ordner.
• "3001:3001": Links steht der Port am Server, rechts der im Container. Unter der linken Zahl erreichst du Uptime Kuma im Browser.

Ob die Datei formal stimmt, prüft Compose selbst:

cd ~/uptime-kuma
sudo docker compose config --quiet && echo "Compose-Datei in Ordnung"

Compose-Datei in Ordnung

Meldet Compose stattdessen einen Fehler mit Zeilennummer, ist beim Einfügen meist die Einrückung verrutscht. YAML zählt Leerzeichen und verträgt keine Tabulatoren.

Schritt 3: Uptime Kuma starten

cd ~/uptime-kuma
sudo docker compose up -d

Beim ersten Mal lädt Docker das Image herunter. Das -d lässt den Container im Hintergrund weiterlaufen, und restart: unless-stopped holt ihn nach einem Neustart des Servers von selbst zurück. Gib ihm eine knappe Minute und klopf dann selbst an:

curl -sI http://localhost:3001 | head -n 1

HTTP/1.1 302 Found

Die 302 ist eine Weiterleitung, und hier ist sie genau richtig: Uptime Kuma schickt jeden Besucher zur Einrichtung, solange es noch kein Admin-Konto gibt. Kommt gar keine Zeile zurück, läuft der Container noch hoch oder ist abgestürzt; sudo docker compose logs --tail 30 zeigt dann, warum. Dass die Datenbank schon als Datei auf deinem Server liegt, zeigt dieser Befehl:

sudo ls ~/uptime-kuma/data | grep -xE 'kuma\.db|db-config\.json'

db-config.json
kuma.db

kuma.db ist die SQLite-Datenbank, in der bald alle Monitore und ihr Verlauf stehen, db-config.json merkt sich die Wahl aus der Compose-Datei. Beide gehören ins Backup. Das sudo vor ls braucht es, weil Uptime Kuma im Container als root schreibt.

Schritt 4: Admin-Konto anlegen

Geklappt hat es, wenn du auf dem Dashboard landest, links die noch leere Monitorliste. Eine Frage nach der Datenbank kommt nicht, die hat die Compose-Datei schon beantwortet. Uptime Kuma prüft bei der Einrichtung nur, ob beide Passwortfelder übereinstimmen; eine Mindestlänge verlangt das Formular nicht. Das Passwort ist also genau so stark, wie du es machst.

Schritt 5: Ein ntfy-Topic würfeln

Ein Topic auf ntfy.sh hat kein Passwort. Wer den Namen kennt, liest mit, und Namen wie „homelab“ oder „kuma“ hat womöglich schon jemand anderes in Gebrauch. Ein zufälliger Name schützt davor. Den würfelt dir die Shell:

echo "kuma-$(openssl rand -hex 8)"

Heraus kommt etwas wie kuma-3f9a1c7e5b2d4086, bei dir mit anderen Zeichen. Kopier dir den Namen, du brauchst ihn gleich zweimal. Anlegen musst du das Topic nirgends, laut ntfy-Doku entsteht es, sobald jemand eine Nachricht hineinschickt.

Schritt 6: Der erste Monitor, mit Alarm

Als erstes Ziel nehme ich die Webseite von Debian. Sie ist zuverlässig erreichbar, und dein Server kennt sie ohnehin. Deine eigenen Dienste kommen später nach demselben Muster dazu. Die Benachrichtigung richtest du direkt im Monitor-Formular mit ein.

Ob die Testnachricht angekommen ist, fragst du beim ntfy-Server selbst nach. Statt des Beispiel-Topics setzt du deinen Namen ein; since=latest holt nur die jüngste Nachricht, und grep schneidet den Text heraus:

curl -s "https://ntfy.sh/kuma-3f9a1c7e5b2d4086/json?poll=1&since=latest" | grep -o '"message":"[^"]*"'

"message":"ntfy Testing"

„ntfy Testing“ setzt Uptime Kuma aus dem Namen der Benachrichtigung und dem Wort „Testing“ zusammen. Steht die Zeile da, ist der Weg vom Server bis zum Topic frei. Aufs Handy kommt die Meldung, sobald du dasselbe Topic in der ntfy-App abonnierst, die es für Android und iPhone gibt; im Browser geht es unter https://ntfy.sh/ plus Topic-Name.

Die Wiederholungen sind die Einstellung, die über deinen Schlaf entscheidet. Mit Version 2 hat Uptime Kuma den Standard für neue Monitore von 1 auf 0 gesenkt; so steht es auf der Migrationsseite im Wiki. Bei 0 reicht eine einzige verpasste Antwort für einen Alarm, und ein Dienst, der beim nächtlichen Update zehn Sekunden schweigt, weckt dich um drei Uhr. Mit 2 setzt Uptime Kuma den Monitor bei der ersten Panne erst auf „Ausstehend“, fragt im Abstand von 60 Sekunden zweimal nach, und erst wenn auch das scheitert, steht er auf „Offline“ und die Meldung geht raus. Ein echter Ausfall kommt so rund zwei Minuten später an. Diesen Tausch würde ich für alles im Heimnetz machen.

Geklappt hat es, wenn der Monitor links in der Liste auftaucht und auf seiner Seite ein grünes „Online“ trägt, während die ersten grünen Balken einlaufen. Daneben steht die Antwortzeit in Millisekunden. Das ist der erste Herzschlag, den dein Server aufzeichnet, und ab jetzt merkt er sich jeden.

Was am Ende eingestellt ist

Admin-Konto, Datenbank, Wiederholungen und eine Benachrichtigung für jeden neuen Monitor stehen schon. Drei Dinge gehören noch dazu, bevor du die übrigen Dienste einträgst.

1. Ein Backup, das du auch machst

Wer Uptime Kuma 1 kennt, sucht in den Einstellungen den Punkt „Sicherung“ mit JSON-Export. In Version 2 ist er weg, die Migrationsseite im Wiki führt das als bewussten Bruch. Die Sicherung ist jetzt der Datenordner. Ich halte den Container dafür kurz an, denn eine SQLite-Datei, in die gerade geschrieben wird, kopiert man besser nicht im Flug:

cd ~/uptime-kuma
sudo docker compose stop
sudo tar -czf ~/uptime-kuma-data.tar.gz data
sudo docker compose start

tar -czf packt den Ordner data in ein Archiv in deinem Home-Verzeichnis. Während der kurzen Pause fällt die Überwachung aus, das ist der Preis für eine saubere Kopie. Ob die Datenbank im Archiv steckt, zeigt:

tar -tzf ~/uptime-kuma-data.tar.gz | grep -x 'data/kuma.db'

data/kuma.db

Ein Archiv auf derselben Platte stirbt mit ihr. Es gehört auf ein zweites Gerät, verschlüsselt und regelmäßig, zum Beispiel mit Kopia. Ja, auch für einen Dienst, der nur zuschaut: Dreißig Monitore mit Intervallen, Wiederholungen und Benachrichtigungen neu einzutragen, kostet einen Abend.

2. Updates mit dem Tag 2

Das Tag 2 holt jede neue 2er-Version, auch die mit Sicherheitskorrekturen; 2.5.9 hat etwa eine Lücke im RSS-Cache der Statusseiten geschlossen. Automatisch passiert das nicht, du stößt es an. Die Befehle stehen so im Wiki:

cd ~/uptime-kuma
sudo docker compose pull
sudo docker compose up -d --force-recreate

Danach meldet der curl-Befehl aus Schritt 3 wieder eine Zeile, die mit HTTP/1.1 beginnt, und die Monitore laufen weiter, wo sie aufgehört haben. Vor jedem Update ein frisches Backup nach Punkt 1, vor dem späteren Sprung auf Version 3 sowieso. Den machst du nicht nebenbei: Release Notes und Migrationsseite lesen, Backup, erst dann das Tag von 2 auf 3 ändern.

3. Port 3001 und das Konto schützen

Port 3001 spricht unverschlüsseltes HTTP, auch dein Passwort geht so durchs Netz. Im eigenen Heimnetz ist das vertretbar, im Internet nicht: keine Portfreigabe. Von unterwegs kommst du über ein VPN ins Heimnetz, etwa mit wg-easy. HTTPS mit eigenem Namen läuft über einen Reverse Proxy wie den Nginx Proxy Manager; das ist Stoff für einen eigenen Beitrag.

Wer in Uptime Kuma hineinkommt, sieht die Adressen aller deiner Dienste und dein ntfy-Topic. Ein zweiter Faktor für das Admin-Konto liegt unter Einstellungen, Sicherheit, 2FA-Einstellungen und braucht eine Authenticator-App. Backup-Codes zeigt der Dialog laut Quellcode nicht an; wer 2FA einschaltet, legt deshalb vor dem Scannen die Zeile hinter URI anzeigen im Passwort-Manager ab.

Wo es klemmt

Der Wächter fällt mit dem Bewachten. Läuft Uptime Kuma auf demselben Server wie deine Dienste und dieser Server geht aus, meldet niemand etwas, denn der Melder ist mit aus. Gegen einzeln abstürzende Container hilft alles wie beschrieben. Gegen den Totalausfall hilft nur ein zweiter, kleiner Rechner, der mit dem Hauptserver nichts teilt außer dem Netz. Ich würde ihn genau dafür anschaffen, sobald mehr als eine Handvoll Dienste daran hängt.

Datenordner auf einem Netzlaufwerk. Das README warnt ausdrücklich, dass Netzwerk-Dateisysteme wie NFS nicht unterstützt werden. ./data gehört auf die lokale Platte des Servers. Aufs NAS wandert das Archiv aus dem Backup, nicht der laufende Ordner.

Alarm, obwohl alles läuft. Fast immer stehen die Wiederholungen noch auf 0. Monitor öffnen, Bearbeiten, Wiederholungen auf 2. Schlägt ein Dienst danach trotzdem regelmäßig an, ist er vermutlich zu langsam für das Anfrage-Timeout im selben Formular.

Plötzlich wieder die Datenbank-Frage. Wer die Zeile UPTIME_KUMA_DB_TYPE beim Abtippen weglässt und mit leerem Ordner data startet, landet auf der Auswahlseite im Browser. Liegt schon eine kuma.db im Ordner, erkennt Uptime Kuma laut Quellcode SQLite von selbst; die Zeile in der Compose-Datei macht die Wahl trotzdem sichtbar.

Der Docker-Container-Monitor will nicht. Den Monitortyp „Docker-Container“ gibt es, er braucht aber Zugriff auf den Docker-Socket, und wer den hat, darf auf dem Server praktisch alles. Für den Anfang reicht es, jeden Dienst über seine Web-Adresse zu prüfen: Antwortet die, läuft auch der Container.

Für wen sich Uptime Kuma lohnt

Ab dem zweiten Dienst, den jemand außer dir benutzt. Solange du allein bastelst, merkst du Ausfälle selbst. Sobald die Familie Fotos auf deinem Server ablegt oder Passwörter von dort holt, ist ein Wächter, der dich vor allen anderen informiert, die billigste Versicherung, die du in einer halben Stunde aufsetzen kannst. Und die Oberfläche versteht man ohne Handbuch, was bei Überwachungswerkzeugen keine Selbstverständlichkeit ist.

Welcher deiner Dienste bekommt als Nächstes einen Monitor, und auf welchem Weg soll dich der Alarm erreichen? Schreib's in die Kommentare.

Wenn du zu den Alarmen auch sehen willst, wo im Netz der ausgefallene Dienst eigentlich steht: Homelable zeichnet dein Homelab als Netzwerkplan mit Live-Status, und die beiden vertragen sich gut.

Quellen

• Docker-Doku: Docker Engine auf Debian installieren
• Uptime Kuma auf GitHub (README: Installation, Benachrichtigungen, NFS-Hinweis, Lizenz)
• Uptime Kuma: offizielle compose.yaml
• Uptime Kuma: Releases (2.5.9)
• Uptime-Kuma-Wiki: Environment Variables (UPTIME_KUMA_DB_TYPE)
• Uptime-Kuma-Wiki: Docker Tags
• Uptime-Kuma-Wiki: How to Update
• Uptime-Kuma-Wiki: Migration from v1 to v2 (JSON-Backup entfernt, Wiederholungen 0)
• Uptime-Kuma-Wiki: Migration from v2 to v3 (Beta, kein Downgrade)
• Quellcode 2.5.9: Datenbank-Einrichtung und Umgebungsvariablen
• Quellcode 2.5.9: ntfy-Benachrichtigung
• Quellcode 2.5.9: Admin-Konto anlegen
• Quellcode 2.5.9: Monitor-Formular und Standardwerte
• Quellcode 2.5.9: 2FA-Dialog
• Quellcode 2.5.9: deutsche Übersetzung der Oberfläche
• ntfy-Doku: Nachrichten per API abrufen (poll, since=latest)
• ntfy-Dokumentation (Topics, App)