Uptime Kuma Docker Compose einrichten

Uptime Kuma Docker Compose einzurichten ist der direkte Weg zu einem eigenen Verfügbarkeitsmonitor im Homelab. Du legst eine kleine Compose-Datei mit persistentem Speicher an, startest den Dienst und richtest anschließend Monitore über die Weboberfläche ein. So bleiben Konfiguration und Messdaten auch nach einem Container-Neustart erhalten.

Stand: 06.10.2026

Auf einen Blick

• Uptime Kuma ist ein selbst gehostetes Werkzeug zur Überwachung von Diensten.
• Das offizielle Image der aktuellen Hauptversion lautet louislam/uptime-kuma:2.
• Der Persistenzpfad im Container ist /app/data; ohne Volume gehen Einstellungen beim Ersetzen des Containers verloren.
• Der Dienst ist nach dem Start standardmäßig über Port 3001 erreichbar.
• Lege das Datenverzeichnis auf lokalem Speicher an, nicht auf NFS.

Was ist Uptime Kuma?

Uptime Kuma ist ein selbst gehostetes Monitoring-Tool, das die Erreichbarkeit und ausgewählte Eigenschaften von Diensten prüft. Laut dem offiziellen Projekt unterstützt es unter anderem HTTP(S), TCP, Keyword- und JSON-Abfragen, WebSocket, Ping, DNS-Einträge, Push-Monitore und Docker-Container.

Damit eignet sich das Tool für Websites, interne Anwendungen und Dienste im Heimnetz. Außerdem bringt es Statusseiten, Zertifikatsinformationen, Zwei-Faktor-Authentifizierung und Benachrichtigungen für zahlreiche Dienste mit. Es ersetzt jedoch kein vollständiges Infrastrukturmonitoring mit Metriken; dafür bleibt ein Stack wie Grafana und Prometheus für Kubernetes die passendere Ergänzung.

Welche Voraussetzungen gelten für Uptime Kuma Docker Compose?

Du brauchst einen Host mit Docker Engine und dem Compose-Plugin. Prüfe außerdem vorab, wo die Daten dauerhaft liegen sollen. Die offizielle Uptime-Kuma-Dokumentation warnt ausdrücklich davor, das Datenverzeichnis auf NFS abzulegen; verwende deshalb lokalen Speicher oder ein Docker-Volume.

Wenn Docker und Compose neu für dich sind, erklärt der Docker-Compose-Einsteiger-Guide die Grundbegriffe. Für ein NAS gilt zusätzlich: Sichere den Host und die Datensicherungen nach den Grundsätzen aus NAS richtig absichern, bevor du Dienste nach außen erreichbar machst.

Uptime Kuma Docker Compose einrichten: so sieht die Datei aus

Die Compose-Datei beschreibt genau einen Dienst. Das folgende Beispiel entspricht der offiziellen Compose-Datei des Projekts: Es nutzt die Hauptversion 2, startet den Container nach einem Neustart des Docker-Daemons wieder und bindet das lokale Verzeichnis ./data an den Datenpfad im Container.

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

Erstelle dafür einen eigenen Ordner, speichere den Inhalt als compose.yaml und starte ihn aus diesem Ordner. Der Startbefehl stammt ebenfalls aus der offiziellen Installationsanleitung:

docker compose up -d

Danach erreichst du die Ersteinrichtung unter http://HOSTNAME-ODER-IP:3001. Vergib dort zuerst ein Administratorkonto. Die Projektanleitung nennt Port 3001 und weist darauf hin, dass der Dienst mit der gezeigten Portfreigabe auf den Netzwerkschnittstellen des Hosts lauscht.

Warum ist das Volume für Uptime Kuma Docker Compose wichtig?

Das Volume ist der entscheidende Teil der Uptime-Kuma-Docker-Compose-Konfiguration. Es verbindet den Ordner ./data auf dem Host mit /app/data im Container. Dadurch liegen die Anwendungsdaten außerhalb des flüchtigen Container-Dateisystems.

Docker beschreibt Volumes und Bind-Mounts als Zuordnung zwischen Quelle auf dem Host und Ziel im Container. Relative Pfade wie ./data werden beim lokalen Compose-Einsatz relativ zum Verzeichnis der Compose-Datei aufgelöst. Lege die Datei deshalb bewusst in einem Ordner ab, den du sichern kannst.

Wie richtest du den ersten Monitor ein?

Nach der Anmeldung legst du einen Monitor über die Oberfläche an. Wähle zuerst den Prüfmodus, trage danach Ziel und Intervall ein und speichere. Für eine Webanwendung ist HTTP(S) meist der passende Start; für einen Dienst ohne Weboberfläche kommen je nach Protokoll TCP oder Ping infrage.

1. Öffne die Uptime-Kuma-Weboberfläche auf Port 3001.
2. Erstelle einen neuen Monitor und wähle den passenden Typ.
3. Trage eine URL, einen Hostnamen oder die für den Typ nötigen Angaben ein.
4. Speichere den Monitor und prüfe, ob der Status sinnvoll angezeigt wird.
5. Richte anschließend eine Benachrichtigung ein, damit ein Zustandswechsel nicht nur im Dashboard sichtbar bleibt.

Beginne mit wenigen wichtigen Zielen, zum Beispiel dem Reverse Proxy, dem NAS und einer zentralen Anwendung. Dadurch bleiben Fehlalarme überschaubar. Ein HTTP-Monitor zeigt nur, dass die gewählte Anfrage eine Antwort liefert; er ersetzt daher keine fachliche Prüfung eines komplexen Dienstes.

Soll Uptime Kuma über einen Reverse Proxy erreichbar sein?

Ja, wenn du die Oberfläche per HTTPS und unter einem Namen bereitstellen willst, ist ein Reverse Proxy der saubere Weg. Dann veröffentlichst du nicht zwingend Port 3001 direkt ins Internet, sondern leitest den Zugriff über den Proxy weiter. Für die Grundlagen zeigt die Anleitung Traefik im Homelab mit Docker Compose den passenden Kontext.

Trenne dabei die Frage nach externem Zugriff von der eigentlichen Uptime-Kuma-Docker-Compose-Installation. Ein Monitor kann auch interne Namen und private Adressen prüfen. Öffne Verwaltungsoberflächen nur dann nach außen, wenn Authentifizierung, HTTPS und der Zugriffspfad bewusst eingerichtet sind.

Welche Fehler treten bei Uptime Kuma Docker Compose häufig auf?

Die Weboberfläche ist nicht erreichbar. Prüfe zunächst, ob die Portfreigabe in der Compose-Datei steht und ob du Hostname beziehungsweise IP-Adresse korrekt verwendest. Außerdem kann eine Firewall auf dem Docker-Host oder im Netz den Zugriff blockieren.

Nach einer Neuerstellung sind Monitore verschwunden. In diesem Fall fehlt häufig die Zeile unter volumes, oder der Start erfolgte aus einem anderen Verzeichnis als erwartet. Kontrolliere deshalb, ob der Ordner data neben der verwendeten Compose-Datei liegt und beschreibbar ist.

Die Daten liegen auf einem Netzlaufwerk. Das Projekt nennt NFS ausdrücklich als nicht unterstützt. Verschiebe den Datenpfad daher auf lokalen Speicher oder verwende ein lokales Docker-Volume, bevor du dich auf die gespeicherten Daten verlässt.

Der Dienst startet nach einem Host-Neustart nicht automatisch. Die offizielle Compose-Datei nutzt restart: unless-stopped. Prüfe zusätzlich, ob Docker auf dem Host selbst beim Systemstart aktiviert ist.

Wie wartest du die Installation sinnvoll?

Dokumentiere den Speicherort der Compose-Datei und sichere den Datenordner regelmäßig zusammen mit deiner übrigen Homelab-Konfiguration. Lies vor einem Update die offizielle Update-Anleitung von Uptime Kuma, denn sie ist die maßgebliche Quelle für den jeweiligen Upgrade-Weg.

Halte außerdem Image-Tag und Compose-Datei nachvollziehbar. Docker empfiehlt für produktive Compose-Anwendungen unter anderem eine passende Neustart-Richtlinie und getrennte, umgebungsspezifische Konfigurationen, wenn diese nötig werden. So bleibt ein einfacher Einzelcontainer später erweiterbar, ohne die Grundinstallation zu vermischen.

Fazit

Mit Uptime Kuma Docker Compose erhältst du einen übersichtlichen, selbst gehosteten Einstieg in die Verfügbarkeitsüberwachung. Entscheidend sind der persistente lokale Datenpfad und eine bewusst gewählte Erreichbarkeit der Oberfläche. Starte klein, sichere die Daten und ergänze Benachrichtigungen erst für die Dienste, auf die du tatsächlich reagieren kannst.

Quellen

• Uptime Kuma: offizielles Repository und Installationsanleitung
• Uptime Kuma: offizielle compose.yaml
• Docker Docs: Compose-Service-Referenz
• Docker Docs: Compose in Produktion verwenden

Häufige Fragen