SSD Nodes Learn
Anleitungen Matt ConnorVon Matt Connor · Aktualisiert 2026-07-24

Uptime Kuma Docker installieren Anleitung

Überwachen Sie Websites und Ports mit Uptime Kuma in Docker. Erstellen Sie Statusseiten und nutzen Sie Telegram oder E-Mail für Alarme bei Dienstausfällen.

Was Sie aufbauen

Ein einzelner kleiner Container, der Ihre anderen Server und Websites von außen überwacht. Er benachrichtigt Sie per E-Mail, Telegram, Discord oder Webhook, sobald ein Dienst nicht mehr antwortet. Uptime Kuma ist ein Node-Prozess, der eine SQLite-Datei nutzt. Er benötigt lediglich 256-512 MB RAM. Das Tool bietet ein Live-Dashboard, historische Diagramme und eine öffentliche Statusseite. Die Installation erfolgt über eine zehnzeilige Compose-Datei. Entscheidend ist, wo Sie den Container ausführen und ob die Benachrichtigungen in einem Test ausgelöst wurden. Ein Monitor, dessen Erreichbarkeit nie getestet wurde, ist unzuverlässig: Er vermittelt eine falsche Sicherheit, während er keine Meldungen liefert.

Führen Sie den Monitor an einem Ort aus, der von einem Ausfall nicht erreicht wird

Diese Entscheidung ist entscheidend für den Erfolg des gesamten Systems. Führen Sie Uptime Kuma nicht auf demselben Server aus, den Sie überwachen. Wenn der Monitor auf dem überwachten Server läuft, führt genau das Ereignis, das Sie überwachen möchten – wie ein Systemabsturz oder Speichermangel –, dazu, dass auch der Monitor ausfällt. Sie erhalten dann keine Benachrichtigung. Das Ausbleiben einer Meldung eines defekten Monitors ist identisch mit dem Status „alles in Ordnung“. Es gibt eine subtilere Falle, solange der Server noch läuft: Ein Monitor, der auf localhost zeigt, teilt sich die CPU mit der Arbeitslast. Ein Lastanstieg kann dazu führen, dass die eigene Überprüfung in ein Timeout läuft und das Ziel fälschlicherweise als down markiert wird. Dies ist ein Fehlalarm, obwohl die echten Benutzer weiterhin bedient werden.

Führen Sie Uptime Kuma daher auf einem anderen VPS aus als dem, den Sie überwachen. Idealerweise nutzen Sie einen anderen Anbieter oder eine andere Region. Der Monitor sollte Ihre Dienste so erreichen, wie es Ihre Benutzer tun: über das öffentliche Internet mittels Hostname. Eine günstige Instanz ist ausreichend, und ein einzelner kleiner Monitoring-VPS kann alle Ihre Server überwachen. Um einen Ausfall von Kuma selbst zu erkennen, fügen Sie an einem anderen Ort einen Push-Heartbeat via cron hinzu.

Voraussetzungen und Dimensionierung

  • Ein frisches Ubuntu 24.04 VPS mit Docker Engine und dem Compose v2 Plugin. Installieren Sie diese aus dem offiziellen Docker apt-Repository und nicht aus dem docker.io Distro-Paket, da dieses veraltet ist.
  • 256 MB RAM reichen für wenige Monitore aus. 512 MB bis 1 GB sind für mehrere Dutzend Monitore plus den Reverse Proxy empfehlenswert, da die CPU zwischen den Prüfungen nahezu im Leerlauf läuft.
  • Eine Domain und ein DNS A-Eintrag (z. B. status.example.com, der auf das VPS zeigt), nur wenn Sie TLS und eine öffentliche Statusseite benötigen. Eine private Instanz kann DNS weglassen und stattdessen ein VPN oder einen SSH-Tunnel nutzen.
  • Eine ausgehende Netzwerkverbindung zu den Zielorten der Alerts: SMTP zu Ihrem Mail-Provider oder HTTPS zu Telegram und Discord.

The Compose file

Put this in /srv/uptime-kuma/compose.yaml.

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

volumes:
  kuma-data:

Bring it up and watch the first boot:

sudo mkdir -p /srv/uptime-kuma
# save the file above as /srv/uptime-kuma/compose.yaml, then:
cd /srv/uptime-kuma && sudo docker compose up -d
sudo docker compose logs -f uptime-kuma

A correct start logs Listening on 3001 and goes quiet. Three things in that file are deliberate.

127.0.0.1:3001:3001, not 3001:3001. Docker publishes ports with DNAT rules evaluated before ufw ever sees the packet, so a bare 3001:3001 puts your dashboard on the public internet regardless of your firewall. Binding to loopback keeps it private, with only the reverse proxy exposed; a private instance can skip the proxy and reach 3001 over a self-hosted WireGuard VPN instead.

A named volume at /app/data. Everything Uptime Kuma remembers, the SQLite database, your monitors, notification settings and status-page logos, lives there. Lose it and you start from an empty admin screen; it is the only thing you must back up.

The image is pinned to a major tag, :2. That is the current stable line; check Docker Hub for the newest major before copying it, and never track a moving tag like latest, which the project deprecates. A major-version jump on this image is a one-way database migration you want to trigger deliberately, not stumble into on a routine pull.

One caveat: /app/data must sit on a filesystem with POSIX file locks. A local Docker volume is fine; on NFS the SQLite database corrupts and you get SQLITE_BUSY and database disk image is malformed, so never use a network share.

Erster Durchlauf: Admin-Konto erstellen

Rufen Sie die Instanz über Ihren Proxy unter https://status.example.com oder über einen SSH-Tunnel auf: Führen Sie ssh -L 3001:127.0.0.1:3001 user@your-vps aus und öffnen Sie http://localhost:3001. Die erste Seite ist ein Setup-Formular für den Benutzernamen und das Passwort des Administrators; es gibt keine Standard-Anmeldung. Wählen Sie ein sicheres Passwort: Dieses Dashboard sieht die internen Adressen und Token aller überwachten Komponenten. Passwort vergessen? Das Zurücksetzen erfolgt über den Host, nicht über den Browser:

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

Fügen Sie zuerst Ihre Benachrichtigungskanäle hinzu und testen Sie diese

Richten Sie Alerts ein, bevor Sie Monitore hinzufügen. So können Sie bei der Erstellung jedes Monitors direkt einen Kanal zuweisen. Gehen Sie zu Settings then Notifications then Setup Notification. Nutzen Sie die Test-Schaltfläche jedes Kanals, um den Nachrichteneingang zu bestätigen. Eine nicht getestete Benachrichtigung ist die zweithäufigste Ursache für ein stillschweigendes Scheitern der Einrichtung.

Email (SMTP). Geben Sie Host, Port, Verschlüsselung, Benutzername, Passwort, From und To ein. Die zwei funktionierenden Kombinationen sind 465 mit der Einstellung "Secure" auf TLS/SSL oder 587 mit STARTTLS. Bei Gmail und den meisten Anbietern mit Zwei-Faktor-Authentifizierung müssen Sie ein App-Passwort generieren; ein normales Kontopasswort führt zu Error: Invalid login: 535-5.7.8 Username and Password not accepted.

Telegram. Senden Sie eine Nachricht an @BotFather, senden Sie /newbot und kopieren Sie den Bot-Token. Um Ihre Chat-ID zu erhalten, senden Sie einmal eine Nachricht an den neuen Bot, öffnen Sie https://api.telegram.org/bot<token>/getUpdates und lesen Sie chat.id aus dem JSON aus. Ein Bot, dem Sie noch nie geschrieben haben, hat einen leeren getUpdates und kann keine Nachrichten senden.

Discord. Öffnen Sie im Kanal Edit Channel then Integrations then Webhooks then New Webhook, kopieren Sie die URL und fügen Sie diese als Discord-Benachrichtigung ein.

Generic webhook. Für alle anderen Dienste, wie Slack incoming webhooks, benutzerdefinierte Endpunkte oder Home-Automation-Hooks: Der Typ Webhook sendet einen JSON-Payload per POST an eine von Ihnen angegebene URL. Die integrierte Apprise-Integration unterstützt die meisten der über neunzig anderen Dienste auf der Liste.

Überwachung hinzufügen, ein Typ nach dem anderen

Klicken Sie auf Add New Monitor, wählen Sie einen Typ aus und legen Sie den Friendly Name, das Check Interval (60 Sekunden sind angemessen), die Retries (aufeinanderfolgende Fehler vor dem Status "down"; 2 oder 3 verhindern Fehlalarme durch einzelne Paketverluste) sowie die Benachrichtigungen fest. Die verwendeten Typen sind:

  • HTTP(s). Eine vollständige URL. "Up" bedeutet ein akzeptierter Statuscode (standardmäßig 200-299; erweitern Sie diesen unter Accepted Status Codes, falls 301 oder 401 für Sie normal sind). Dies ist die Standardmethode für Websites und APIs.
  • HTTP(s) - Keyword. Die gleiche Anfrage, aber "up" erfordert zusätzlich das Vorhandensein eines Strings im Body (sofern Invert nicht aktiviert ist). Dies erkennt Fälle, in denen die Seite 200 OK zurückgibt und gleichzeitig "Error establishing a database connection" anzeigt, was ein einfacher HTTP-Check als "healthy" einstufen würde.
  • TCP Port. Eine einfache TCP-Verbindung zu einem Host und Port für Dienste ohne HTTP: SSH auf 22, Postgres auf 5432, ein SMTP-Server auf 25 oder ein Game-Server.
  • Ping. ICMP-Echo: prüft Erreichbarkeit und Latenz mit geringem Ressourcenverbrauch. Da viele Netzwerke und Cloud-Firewalls ICMP blockieren, kann ein roter Ping-Monitor bedeuten, dass der Host offline ist oder der Provider Pings blockiert; verifizieren Sie dies mit einem TCP-Monitor.
  • DNS. Auflösung eines Records (A, AAAA, MX, TXT usw.) über einen definierten Resolver. Dies kann die Antwort validieren und Ausfälle von Registraren oder DNS-Diensten frühzeitig erkennen.
  • Push. Ein "Inside-Out"-Monitor, der im nächsten Abschnitt behandelt wird.

Überwachung eines cron-Jobs mit einem Push-Monitor (Heartbeat)

Alle oben genannten Monitore greifen von außen auf Ihren Dienst zu. Ein Push-Monitor funktioniert umgekehrt: Uptime Kuma wartet, und Ihr Job meldet aktiv den Erfolg. Dies ist die einzige zuverlässige Methode zur Überwachung von Backups oder cron-Jobs: Ein HTTP-Check erkennt lediglich, ob eine URL antwortet, aber nur der Job selbst weiß, ob er erfolgreich abgeschlossen wurde.

Erstellen Sie einen Monitor vom Typ Push. Uptime Kuma generiert eine eindeutige URL wie:

https://status.example.com/api/push/j8Xa2Kd9Qe?status=up&msg=OK&ping=

Setzen Sie das Heartbeat Interval auf die Häufigkeit, mit der der Job läuft, plus einen kleinen Puffer. Fügen Sie dann eine Zeile am Ende des Skripts hinzu, damit der Aufruf nur bei Erfolg erfolgt:

#!/usr/bin/env bash
set -euo pipefail
# ... your backup or job runs here; set -e aborts on any failure ...
curl -fsS --retry 3 "https://status.example.com/api/push/j8Xa2Kd9Qe?status=up&msg=backup+ok&ping="

Wenn der Job fehlschlägt, bricht set -e vor dem curl-Befehl ab; wenn der Server offline ist, wird das Skript ebenfalls nicht ausgeführt. In beiden Fällen stoppt der Heartbeat. Sobald das Zeitfenster aus Intervall plus Retries abgelaufen ist, setzt Uptime Kuma den Monitor auf down und sendet eine Benachrichtigung. Behandeln Sie diesen Push-Token als Geheimnis: Jeder, der ihn besitzt, kann einen erfolgreichen Heartbeat vortäuschen.

Erstellen Sie eine öffentliche Statusseite

Eine Statusseite ist die für Kunden sichtbare Ansicht: Sie zeigt an, welche Dienste verfügbar sind und wie deren Verlauf aussieht, ohne das Dashboard preiszugeben. Navigieren Sie zu Status Pages und dann zu New Status Page. Vergeben Sie einen Namen und einen Slug (den öffentlichen Pfad, z. B. /status/main). Ziehen Sie die gewünschten Monitore in Gruppen wie „Websites“ und „APIs“. Fügen Sie ein Logo sowie eine kurze Beschreibung hinzu und klicken Sie auf Save. Sie können die Seite auch an eine eigene Domain binden, sodass status.example.com diese direkt bereitstellt.

Zwei Warnhinweise: Fügen Sie nur Monitore hinzu, die Sie öffentlich machen möchten, da eine Statusseite offenlegt, dass ein Dienst existiert und ob dieser betriebsbereit ist. Das Dashboard bleibt hinter Ihrem Login geschützt, während die Statusseite absichtlich öffentlich ist und keine Authentifizierung benötigt.

Nutzen Sie einen Reverse Proxy mit TLS und beachten Sie WebSockets

Schalten Sie bei einer öffentlichen Instanz einen Reverse Proxy vor den auf Loopback bindenden Container, um TLS und einen Hostnamen zu nutzen. Ein häufiger Fehler: Die Benutzeroberfläche von Uptime Kuma ist eine Live-Socket.IO-App, daher muss der Proxy die WebSocket-Verbindung per Upgrade herstellen. Ohne diese Einstellung lädt die Seite zwar, stellt aber keine Verbindung her; das Dashboard zeigt dauerhaft „Connecting...“ an, die Live-Heartbeats aktualisieren sich nicht und die Browser-Konsole zeigt WebSocket connection to 'wss://.../socket.io/...' failed an.

Installieren Sie nginx und certbot und erstellen Sie den Vhost, der auf den Loopback-Port weiterleitet. Nutzen Sie vorerst Port 80 und lassen Sie TLS nachträglich durch certbot hinzufügen; die Herausforderungen, der Erneuerungs-Timer und die Fehlerursachen werden in issuing Let's Encrypt certificates with certbot and nginx behandelt.

sudo apt install -y nginx certbot python3-certbot-nginx

Speichern Sie dies als /etc/nginx/sites-available/status.example.com; die beiden WebSocket-Zeilen sind entscheidend:

server {
    listen 80;
    server_name status.example.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }
}

Aktivieren Sie die Seite, testen Sie die Konfiguration und lassen Sie certbot den Block für Port 443 umschreiben, das Zertifikat einfügen und einen HTTP-zu-HTTPS-Redirect hinzufügen:

sudo ln -s /etc/nginx/sites-available/status.example.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d status.example.com

Das Paar Upgrade und Connection "upgrade" ist entscheidend, und proxy_read_timeout 3600s verhindert, dass nginx die lang laufende Socket-Verbindung trennt; certbot kopiert beide in den generierten 443-Block. Wenn Sie bereits mehrere Container hinter einem Proxy betreiben, ermöglicht routing them through Traefik with automatic TLS dasselbe über Container-Labels und leitet WebSocket-Upgrades standardmäßig weiter.

Nutzen Sie keine Basic-Auth für den gesamten Vhost, da dies auch die öffentliche Statusseite und den /api/push-Endpunkt sperrt. Behalten Sie das integrierte Login von Uptime Kuma bei und installieren Sie fail2ban watching for repeated failed logins, falls die Instanz über das Internet erreichbar ist. Falls das Dashboard nicht öffentlich zugänglich sein muss, verzichten Sie auf den Proxy und greifen Sie über ein VPN darauf zu.

Zertifikatsablauf korrekt überwachen

Ein HTTP(s)-Monitor kann Sie vor dem Ablauf eines TLS-Zertifikats warnen: Aktivieren Sie Certificate Expiry Notification, damit Uptime Kuma eine bestimmte Anzahl an Tagen im Voraus alarmiert. Zwei Fehler führen zu falschen Ergebnissen. Überwachen Sie nach Hostname, nicht nach IP. Ohne SNI erhält eine Anfrage das Standardzertifikat des Servers, was zu Hostname/IP does not match certificate's altnames führt. Aktivieren Sie zudem nicht Ignore TLS/SSL Error bei einem Monitor, für den Sie Ablaufwarnungen erhalten möchten: Diese Option ist für selbstsignierte interne Hosts gedacht (unable to verify the first certificate, DEPTH_ZERO_SELF_SIGNED_CERT), verhindert jedoch, dass Uptime Kuma das Zertifikat überhaupt prüft, einschließlich des Ablaufdatums.

Backups: it is one directory

Because everything lives in /app/data, a backup is a copy of that volume taken while the container is stopped, so the SQLite file is consistent:

cd /srv/uptime-kuma
sudo docker compose stop
sudo docker run --rm \
  -v uptime-kuma_kuma-data:/data \
  -v /var/backups/kuma:/backup \
  alpine tar czf /backup/kuma-$(date -u +%Y%m%dT%H%M%SZ).tgz -C /data .
sudo docker compose start

Confirm the volume's real name with docker volume ls | grep kuma first, since Compose prefixes it with the project directory. Then copy the tarball off the box, because a backup on the same VPS is a copy, not a backup. Restore is the reverse: stop the stack, extract into an empty /app/data volume, start it.

Upgrades

Upgrades erfolgen durch ein Image-Pull:

cd /srv/uptime-kuma
sudo docker compose pull
sudo docker compose up -d

Der neue Container führt beim ersten Start alle Datenbank-Migrationen aus; beachten Sie docker compose logs -f. Erstellen Sie das oben genannte Backup vor dem Pull. Bleiben Sie innerhalb eines Major-Tags: Der Wechsel von :1 zu :2 ist eine Einweg-Migration. Erstellen Sie daher zuerst ein Backup und prüfen Sie die Release Notes.

Fehlerursachen und die angezeigten Meldungen

Falscher Status "down" bei einem Monitor auf localhost. Der Monitor wird rot mit timeout of 48000ms exceeded oder connect ETIMEDOUT, obwohl der Dienst auf Ihrem Laptop antwortet. Wenn der Monitor denselben Host anspricht, auf dem Uptime Kuma läuft, hat ein CPU- oder Memory-Spike die Prüfung blockiert, nicht das Zielsystem. Verschieben Sie den Monitor auf einen separaten VPS und nutzen Sie den öffentlichen Hostnamen als Ziel.

connect ECONNREFUSED 127.0.0.1:443 (oder ein beliebiger Port). Es wurde nichts auf diesem Port gehört: Entweder ist der Dienst offline oder Sie überwachen localhost innerhalb des Containers, wobei 127.0.0.1 der Container ist und nicht Ihr Server. Überwachen Sie den öffentlichen Hostnamen, nicht die Loopback-Adresse.

Invalid login: 535-5.7.8 Username and Password not accepted bei einem E-Mail-Test. Die SMTP-Anmeldedaten sind falsch oder der Anbieter erfordert ein anwendungsspezifisches Passwort, Sie haben jedoch das Kontopasswort verwendet. Erstellen Sie ein anwendungsspezifisches Passwort und verwenden Sie dieses.

connect ETIMEDOUT oder queryA ETIMEDOUT <host> bei einem E-Mail-Test. Falscher Port oder der Anbieter blockiert ausgehenden SMTP. Prüfen Sie, ob 465 oder 587 mit der Secure/STARTTLS-Einstellung übereinstimmt, und testen Sie den Zugriff vom Host mit nc -vz smtp.example.com 587. Viele Anbieter blockieren ausgehenden 25 und einige blockieren Submission-Ports, bis eine Anfrage gestellt wird.

self signed certificate oder unable to verify the first certificate bei einem E-Mail-Test. Ihr SMTP-Server verwendet ein Zertifikat, dem Node nicht vertraut; korrigieren Sie das Zertifikat des Mailservers, anstatt das Problem zu ignorieren.

Dashboard hängt bei "Connecting...", Konsole zeigt WebSocket connection ... failed. Der Reverse Proxy führt kein WebSocket-Upgrade durch. Fügen Sie die Header Upgrade und Connection "upgrade" in nginx hinzu oder verwenden Sie einen Proxy wie Traefik oder Caddy, der diese standardmäßig weiterleitet. Das HTML wird geladen, da dies ein normaler HTTP GET-Request ist; nur der Live-Socket benötigt das Upgrade.

Cert-expiry-Monitor warnt nie oder warnt falsch. Entweder ist Ignore TLS/SSL Error aktiviert, was die Zertifikatsprüfung deaktiviert, oder der Monitor nutzt eine IP-Adresse und liest aufgrund fehlendem SNI das falsche Zertifikat aus, was zu Hostname/IP does not match certificate's altnames führt. Deaktivieren Sie die Ignorieren-Option und überwachen Sie per Hostname.

SQLITE_BUSY oder database disk image is malformed in den Logs. Das /app/data-Volume befindet sich auf einem Dateisystem ohne korrekte File-Locking-Funktion, meist NFS; verschieben Sie es auf ein lokales Docker-Volume und stellen Sie es aus einem Backup wieder her.

FAQ

Wo sollte ich meinen Uptime-Monitor ausführen?

Auf einem anderen Server als den überwachten Systemen. Idealerweise bei einem anderen Anbieter oder in einer anderen Region. Der Monitor sollte die Ziele über den Hostnamen über das öffentliche Internet erreichen, genau wie Ihre Benutzer. Wenn der Monitor auf demselben Server wie die Ziele läuft, führt ein Serverausfall dazu, dass auch der Monitor ausfällt. Ein überlasteter Host kann zudem Fehlalarme auslösen, obwohl die Dienste ordnungsgemäß laufen. Ein kleiner, separater VPS vermeidet beide Probleme.

Wie erhalte ich Benachrichtigungen über Telegram oder E-Mail?

Fügen Sie den Kanal unter Settings then Notifications hinzu und verknüpfen Sie ihn mit jedem Monitor. Erstellen Sie für Telegram einen Bot mit @BotFather und lesen Sie chat.id von https://api.telegram.org/bot<token>/getUpdates; verwenden Sie für E-Mail 465 für SSL oder 587 für STARTTLS mit einem App-Passwort, falls Ihr Anbieter eine Zwei-Faktor-Authentifizierung nutzt. Klicken Sie auf Test und bestätigen Sie den Erhalt der Nachricht, bevor Sie sich auf die Benachrichtigung verlassen.

Kann Uptime Kuma Cronjobs oder Backup-Skripte überwachen?

Ja, dafür ist der Push-Monitor gedacht: Uptime Kuma stellt eine URL bereit, die Sie am Ende des Skripts mit curl aufrufen. So wird der Alarm nur bei Erfolg ausgelöst. Wenn der Job fehlschlägt oder der Server offline ist, trifft der Heartbeat nicht ein und Sie werden nach Ablauf des Intervalls benachrichtigt. Dies ist die einzige zuverlässige Methode, um sicherzustellen, dass ein geplanter Job tatsächlich ausgeführt wurde, da eine externe Prüfung den internen Prozess nicht einsehen kann.

Uptime Kuma vs. Zabbix: Was soll ich verwenden?

Uptime Kuma beantwortet die Fragen „Ist der Dienst von außen erreichbar?“ und „Wurde ein Alarm ausgelöst?“ innerhalb von zehn Minuten bei minimalem Ressourcenverbrauch, inklusive Statusseite. Es sammelt keine tiefgehenden Metriken wie CPU-, Speicher- oder Festplatten-Trends oder flächendeckende Schwellenwerte. Für diese Anforderungen ist ein vollständiger Zabbix-Monitoring-Server das leistungsstärkere, agentenbasierte Tool. Viele Nutzer verwenden beide Systeme. Sie sind sich noch unsicher? unsere Übersicht zu Self-Hosting-Optionen für 2026 setzt Monitoring in den richtigen Kontext.

#uptime-kuma#monitoring#docker#self-hosting#status-page