Uptime Kuma mit Docker installieren: Schritt für Schritt

Ein Homelab meldet sich nicht, wenn etwas kaputtgeht. Es wird still, und du merkst es erst, wenn die Paperless-Suche im Kreis dreht oder das Bank-Passwort nicht aus Vaultwarden kommt. Uptime Kuma dreht das um: Es fragt deine Dienste jede Minute, ob sie noch da sind, und schickt dir eine Nachricht, sobald einer nicht antwortet.

Am Ende dieser Anleitung läuft der Wächter als Docker-Container, hat ein Konto, einen ersten Monitor und einen Weg, dich zu erreichen. Der letzte Punkt fehlt in den meisten Anleitungen, und ohne ihn ist Uptime Kuma nur eine hübsche Seite, die du selbst anschauen musst.

Was du brauchst

• Einen Linux-Rechner im Heimnetz, auf dem Docker läuft: Mini-PC, Raspberry Pi oder eine VM auf Proxmox. Uptime Kuma braucht kaum Leistung, ein Pi reicht.
• Docker mit dem Compose-Plugin.
• Port 3001 frei.
• Einen Kanal, über den dich Uptime Kuma erreichen darf: ein Mail-Konto mit SMTP-Zugang, Telegram, ntfy oder Discord. Das brauchst du erst am Ende, die Zugangsdaten suchst du besser jetzt schon zusammen.

Ob Docker da ist, verraten dir zwei Befehle. Beide antworten mit einer Versionsnummer. Der dritte prüft den Port: Antwortet er mit nichts, ist 3001 frei. Steht dort eine Zeile, belegt schon ein anderer Dienst den Port, und wie du den Schuldigen findest, steht in einer eigenen Anleitung.

docker --version
docker compose version
ss -tulpn | grep :3001

Alle Beispielwerte, die im Text vorkommen, stehen hier einmal gesammelt. Du ersetzt sie durch deine eigenen und musst danach nichts mehr nachschlagen.

Schritt 1: Ordner und Bauplan anlegen

Uptime Kuma bekommt einen eigenen Ordner, und darin liegt der Bauplan. Der Editor nano öffnet eine leere Datei; du fügst den Inhalt ein, speicherst mit Strg+O und Enter und schließt mit Strg+X.

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

Das ist die Datei, wie das Projekt sie selbst im Repository mitliefert. Ich habe nichts daran geändert, und ich würde es auch nicht tun.

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      # <Host Port>:<Container Port>
      - "3001:3001"

Vier Zeilen tragen die Last. image mit der 2 am Ende holt die aktuelle Version 2, das ist laut der Docker-Tags-Seite des Projekts der empfohlene Tag. Die Versuchung heißt latest, und genau die ist hier falsch: Das Wiki schreibt, dieser Tag sei veraltet und zeige weiterhin auf Version 1. Wer ihn aus Gewohnheit tippt, installiert die alte Generation.

restart: unless-stopped sorgt dafür, dass der Container nach einem Neustart des Rechners von selbst wieder hochkommt. ./data:/app/data legt alles, was Uptime Kuma sich merkt, in den Unterordner data neben dem Bauplan. Ohne diese Zeile wäre nach jedem Neubau des Containers alles weg: Monitore, Konto, Verlauf. Und 3001:3001 macht die Oberfläche unter Port 3001 erreichbar.

Ob die Datei stimmt, prüft Docker selbst. Der Befehl gibt den Bauplan aufgelöst zurück; taucht stattdessen eine Fehlermeldung mit Zeilennummer auf, ist meist die Einrückung verrutscht. YAML zählt Leerzeichen.

docker compose config

Schritt 2: Container starten

Ein Befehl, im Ordner mit dem Bauplan. Docker lädt das Image herunter und startet den Container im Hintergrund, dafür steht das -d.

docker compose up -d

Der zweite Befehl zeigt, ob er läuft: In der Spalte STATUS steht Up und eine Zeitangabe. Steht dort Restarting oder Exited, zeigt dir der dritte Befehl die letzten Zeilen des Protokolls, und die Fehlermeldung darin ist der Suchbegriff für den Abschnitt „Wo es klemmt“.

docker compose ps
docker compose logs --tail 30

Bei Uptime Kuma läuft der Container in der Regel beim ersten Versuch. Das freut mich, und trotzdem traue ich einem Container erst, wenn ich seine Seite im Browser gesehen habe. Ein Prozess, der läuft, ist noch kein Dienst, der antwortet.

Schritt 3: Datenbank und Konto im Browser

Jetzt der Browser. Beim ersten Aufruf begrüßt dich Uptime Kuma 2 mit einer Frage, die es in Version 1 nicht gab.

Ich würde SQLite nehmen, und die Oberfläche sagt selbst, warum: „Eine einfache Datenbankdatei, empfohlen für kleine Installationen.“ Deine ganze Überwachung liegt dann in einer Datei im Ordner data, und ein Backup ist eine Kopie dieses Ordners. MariaDB lohnt sich, wenn hunderte Monitore im Sekundentakt schreiben. Ein Homelab mit zwanzig Diensten ist davon weit entfernt.

Startet die Oberfläche auf Englisch, stellst du die Sprache später unter Einstellungen → Darstellung um. Die deutschen Menünamen in dieser Anleitung sind die aus der Übersetzung des Projekts.

Das Passwort gehört in deinen Passwort-Manager, nicht auf den Zettel am Monitor. Vaultwarden wäre einer, den Uptime Kuma gleich mitüberwachen kann. Und falls das Passwort doch verloren geht: Das Wiki beschreibt einen Weg über die Shell, zuerst in den Container, dann der Reset-Befehl.

docker compose exec uptime-kuma bash
npm run reset-password

Schritt 4: Der erste Monitor

Der Router ist der beste erste Kandidat: Er hat eine Weboberfläche, er ist immer an, und wenn er ausfällt, fällt alles aus.

Nach dem Speichern springt die Ansicht auf den Monitor. Innerhalb weniger Sekunden erscheint der erste grüne Balken, daneben die Antwortzeit in Millisekunden und oben der Zustand Up. Bleibt der Balken rot, stimmt meist die URL nicht: Manche Router antworten nur auf https:// und lehnen http:// ab. Probier die andere Variante, bevor du woanders suchst.

Der erste grüne Balken ist ein kleiner Moment, und ich finde, man darf ihn haben. Danach kommen die anderen Dienste dran: Für alles mit Weboberfläche bleibt der Typ HTTP(s), für Dienste ohne Webseite gibt es TCP Port, für Geräte, die nur da sein sollen, Ping. Der Typ Docker-Container braucht Zugriff auf den Docker-Socket des Rechners, und das Wiki warnt deutlich: Wer den Socket in den Container reicht, gibt Uptime Kuma die Kontrolle über den ganzen Docker-Dienst. Solange die Oberfläche nur im Heimnetz erreichbar ist, ist das vertretbar; ins Internet gehört so eine Installation nicht.

Die fünf Einstellungen, die aus dem Dashboard einen Wachdienst machen

Bis hierhin steht in jeder Anleitung dasselbe. Was danach kommt, entscheidet, ob dich Uptime Kuma nachts anruft oder ob du morgens selbst nachsehen musst.

1. Der Kanal zu dir

Ab Werk hat kein Monitor eine Benachrichtigung. Uptime Kuma sieht den Ausfall, malt den Balken rot, und das war es. Der Kanal ist die eine Einstellung, ohne die der Rest keinen Sinn hat.

Die Erfolgskontrolle ist die Testnachricht auf deinem Handy. Kommt keine, stimmen die Zugangsdaten nicht, und dieser Moment ist der richtige, das herauszufinden. Die zwei Haken sind der Teil, den man leicht übersieht: Ohne den zweiten bleibt der Router-Monitor aus Schritt 4 stumm, weil eine Benachrichtigung nur für die Monitore gilt, denen sie zugeordnet ist. Der erste sorgt dafür, dass jeder neue Monitor sie automatisch bekommt. Mehr als 90 Dienste stehen zur Auswahl; ich würde den nehmen, dessen Ton dich auch nachts weckt.

2. Wiederholungen, damit nicht jeder Schluckauf klingelt

Steht Wiederholungen bei einem Monitor auf 0, meldet Uptime Kuma den ersten fehlgeschlagenen Versuch sofort. Ein Router, der nachts die Verbindung neu aufbaut, oder ein Dienst, der gerade ein Update einspielt, produziert dann Fehlalarme. Zwei Wiederholungen heißen: Erst nach drei Fehlschlägen in Folge, also nach etwa zwei Minuten, kommt die Nachricht.

Ein Hinweis aus den Issues: Im Oktober 2025 meldete ein Nutzer für Version 2.0.2, dass ein Gruppen-Monitor die Wiederholungen ignorierte und schon beim ersten Fehler eines Kind-Monitors alarmierte. Das Issue wurde mit einem Pull Request geschlossen. Wenn deine Gruppen also zu früh klingeln, ist die Version die erste Frage.

3. Zwei-Faktor-Anmeldung

Das Dashboard ist die Landkarte deines Homelabs: jede IP, jeder Port, jeder Dienstname. Im Heimnetz reicht ein gutes Passwort. Sobald du die Oberfläche über einen Reverse Proxy nach außen öffnest, ist ein Passwort allein dünn, und der zweite Faktor kostet zwei Minuten.

4. Wie lange der Verlauf bleibt

Uptime Kuma behält den Verlauf ab Werk 365 Tage. Jeder Heartbeat ist eine Zeile in der Datenbankdatei, bei zwanzig Monitoren im Minutentakt sind das rund 29.000 Zeilen am Tag. Für ein Homelab reichen 90 Tage. Der Grund steht im Migrations-Wiki des Projekts: Louis Lam schreibt, seine eigene Installation mit 20 Monitoren und 90 Tagen Verlauf habe für den Umzug auf Version 2 rund sieben Minuten gebraucht. Vier Mal so viel Verlauf ist vier Mal so lange Warten, genau dann, wenn man es am wenigsten will.

5. Backup, weil der eingebaute Export weg ist

Version 1 hatte unter Einstellungen einen Menüpunkt „Sicherung“ mit Export und Import. Version 2 hat ihn nicht mehr; in den Release-Notes zur ersten Beta steht schlicht „Removed backup and restore functionality“. Das Backup ist jetzt dein Ordner data, und weil darin eine SQLite-Datei liegt, hältst du den Container zum Kopieren kurz an. Eine Datenbank, die während des Kopierens beschrieben wird, ist im Archiv nicht mehr dieselbe.

cd ~/uptime-kuma
docker compose stop
tar czf ~/uptime-kuma-backup-$(date +%F).tar.gz data
docker compose start
tar tzf ~/uptime-kuma-backup-$(date +%F).tar.gz | head

Der letzte Befehl listet den Inhalt des Archivs. Steht dort data/kuma.db, ist die Datenbank drin. Das Archiv kopierst du anschließend auf einen anderen Rechner; ein Backup auf derselben Platte ist eine Kopie, kein Backup.

Mir ist klar, dass dieser Absatz in jeder meiner Anleitungen vorkommt. Im Wiki von Uptime Kuma steht er vor dem Update auf Version 2 sogar zweimal hintereinander: „Backup your data directory. Make sure you have a backup of your data directory again.“ Ich nehme an, Louis Lam hat seine Gründe.

Updaten, ohne den Wächter zu verlieren

Der Tag 2 im Bauplan bedeutet: Jedes Update innerhalb von Version 2 holst du mit zwei Befehlen, so wie das Wiki sie angibt. Ein Backup davor ist Pflicht, siehe oben. Der Ordner data bleibt beim Neubau unangetastet, deshalb sind Monitore und Konto danach noch da.

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

Welche Version läuft, steht danach unter Einstellungen → Über. Kommst du von Version 1, gilt zusätzlich das Migrations-Wiki: Container stoppen, data sichern, Tag im Bauplan auf 2 ändern, starten, und dann die Migration im Protokoll durchlaufen lassen. Das Wiki warnt in Großbuchstaben, sie nicht zu unterbrechen, und ein Weg zurück auf Version 1 existiert nicht.

Wo es klemmt

„Cannot connect to the socket server“ hinter einem Reverse Proxy. In den Issues ist das seit 2021 der Dauergast, unter anderem #958, #2059 und #2780. Uptime Kuma redet per WebSocket mit dem Browser, und das Wiki nennt den Grund: Der Proxy muss die Header Upgrade und Connection durchreichen, sonst bricht die Verbindung. Caddy macht das von selbst, bei Nginx sind es zwei Zeilen aus dem Wiki. Ein Unterordner wie meinedomain.de/kuma geht gar nicht, es muss eine eigene Subdomain sein. Was ein Reverse Proxy überhaupt tut, habe ich an anderer Stelle erklärt.

„SQLITE_BUSY: database is locked“ im Protokoll. Issue #7289 beschreibt es für Version 2.2.0, vor allem auf einem Raspberry Pi mit SD-Karte: Die Datenbank kam mit den gleichzeitigen Schreibzugriffen nicht mit. Seit Version 2.3.0 gibt es dafür den Schalter UPTIME_KUMA_SQLITE_SINGLE_CONNECTION. Die Release-Notes schreiben, Raspberry-Pi-Nutzer müssten ihn eventuell auf true setzen, alle anderen könnten ihn ignorieren. Im Bauplan sind das zwei Zeilen unter dem Dienst, eingerückt wie volumes, danach noch einmal docker compose up -d.

    environment:
      - UPTIME_KUMA_SQLITE_SINGLE_CONNECTION=true

Eine zweite Ursache steht in der Installations-Wiki: SQLite braucht ein Dateisystem mit POSIX-Dateisperren. Ein Netzlaufwerk per NFS als data-Ordner ist der klassische Weg zu einer beschädigten Datenbank.

„Permission denied“ oder „chown: Operation not permitted“ beim Start. Auch das taucht in den Issues auf, etwa #694 und #857, und fast immer liegt der Ordner data auf einer NFS-Freigabe, auf der der Container die Besitzrechte nicht ändern darf. Die Lösung ist dieselbe wie eben: data auf die lokale Platte oder in ein Docker-Volume.

Ein Monitor ist rot, aber der Dienst läuft. Das Troubleshooting-Wiki empfiehlt, die Anfrage von innen zu wiederholen: in den Container gehen und die URL von dort aufrufen. curl bringt das Image schon mit; fehlt es doch, holt apt update && apt --yes install curl es nach. Antwortet curl nicht, liegt es am Docker-Netz, nicht am Dienst. Das Wiki nennt zwei häufige Gründe: Nicht jeder Docker-Netztyp darf ins Heimnetz, und IPv6 ist in Docker standardmäßig aus, Dienste nur mit IPv6-Adresse sieht der Container deshalb nicht.

docker compose exec uptime-kuma bash
curl -I http://192.168.178.1

Warum Uptime Kuma zuerst

Ich würde Uptime Kuma als ersten Container auf einen neuen Homelab-Rechner setzen, vor Paperless, vor Immich, vor allem anderen. Der Grund ist nachprüfbar: Er besteht aus einem Container, einem Ordner und einer Compose-Datei mit sieben Zeilen, hat keine Abhängigkeiten und erzählt dir hinterher von allem anderen, wann es ausfällt. Die Installation ist die halbe Stunde, die jeder investiert; die fünf Einstellungen sind der Teil, den kaum jemand macht, und ohne sie hast du einen Bildschirm gekauft und keinen Wächter.

Zwei Dinge habe ich bewusst ausgelassen. Die Statusseiten, mit denen du deiner Familie zeigen kannst, ob das NAS gerade läuft, verdienen einen eigenen Beitrag. Und der Zugriff von außen über einen Reverse Proxy mit Zertifikat ist eine eigene Baustelle, samt der Frage, wer eigentlich meldet, wenn der Wächter selbst ausfällt.

Welche Dienste stehen bei dir auf der Rundgang-Liste, und über welchen Kanal darf dich dein Homelab nachts wecken: Telegram, Mail, ntfy? Und hast du eine Antwort auf die letzte Frage, wer den Wächter bewacht? Schreib es in die Kommentare.

Wenn Uptime Kuma steht, fehlt ihm noch etwas zum Bewachen. Paperless-ngx wäre ein guter erster Kandidat, drei Container, die sich lohnen, im Auge zu behalten.

Quellen

• Uptime Kuma auf GitHub (README, Louis Lam)
• compose.yaml des Projekts
• Wiki: How to Install
• Wiki: How to Update
• Wiki: Docker Tags
• Wiki: Migration From v1 To v2
• Wiki: Reverse Proxy
• Wiki: Troubleshooting
• Wiki: Reset Password via CLI
• Wiki: How to Monitor Docker Containers
• Release 2.5.3, Release 2.3.0 (SQLite-Schalter) und Release 2.0.0-beta.0 (Wegfall von Backup und Restore)
• Docker Hub: Tags von louislam/uptime-kuma
• Issue #7289: SQLITE_BUSY nach 2.2.0 und Pull Request #7312
• Issue #6284: Wiederholungen bei Gruppen-Monitoren
• Issue #2780, #2059 und #958: Cannot connect to the socket server
• Issue #694 und #857: Besitzrechte auf NFS