Uptime Kuma installieren: Server-Monitoring hinter Traefik

Traefik steht – jetzt hängen wir die erste echte App dahinter. Uptime Kuma ist dafür ideal: winzig, sofort nützlich und ohne Datenbank. Es überwacht deine Dienste und schlägt Alarm, wenn einer ausfällt – ab jetzt merkst du zuerst, dass etwas klemmt, nicht deine Nutzer. Nebenbei lernst du das Muster, das jede weitere App wiederholt.

Was bauen wir?

Am Ende läuft Uptime Kuma 2.4 unter https://status.DEINE_DOMAIN, abgesichert über Traefik mit automatischem HTTPS. Du hast den ersten Monitor eingerichtet (der prüft im Minutentakt, ob ein Dienst antwortet), eine Benachrichtigung verbunden und optional eine öffentliche Status-Seite. Zum ersten Mal binden wir dabei einen Dienst an, der nicht auf Port 80 lauscht – ein wichtiges Detail für alle folgenden Apps.

Voraussetzungen

• Ein laufender Traefik-Reverse-Proxy samt proxy-Netzwerk und funktionierendem Let’s-Encrypt-Resolver le
• Ein DNS-Record status.DEINE_DOMAIN, der auf den Server zeigt

Schritt für Schritt

Schritt 1: Die compose.yaml

Eigener Ordner, eigene Datei:

mkdir -p ~/uptime-kuma && cd ~/uptime-kuma

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    volumes:
      - kuma-data:/app/data
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.kuma.rule=Host(`status.DEINE_DOMAIN`)"
      - "traefik.http.routers.kuma.entrypoints=websecure"
      - "traefik.http.routers.kuma.tls.certresolver=le"
      - "traefik.http.services.kuma.loadbalancer.server.port=3001"
    restart: unless-stopped

volumes:
  kuma-data:

networks:
  proxy:
    external: true

Das kennst du aus dem Traefik-Tutorial – bis auf eine neue, entscheidende Zeile:

      - "traefik.http.services.kuma.loadbalancer.server.port=3001"

Uptime Kuma lauscht intern auf Port 3001, nicht auf 80. Diese Zeile sagt Traefik, an welchen Port es die Anfragen weiterreichen soll. Ohne sie rät Traefik falsch und du bekommst einen Bad Gateway. Merke dir das Label – jede App, die nicht auf Port 80 läuft, braucht es.

Der Rest ist das bekannte Muster: kein ports: (nur über Traefik erreichbar), proxy-Netzwerk, Named Volume für die Daten.

Schritt 2: Starten und ersten Login

docker compose up -d
docker compose logs -f uptime-kuma

Wenn Kuma bereit ist, endet das Log mit Waiting for user action... – ab hier wartet der Dienst auf die Ersteinrichtung im Browser (Strg+C beendet nur das Mitlesen):

Welcome to Uptime Kuma
Your Node.js version: 22.22.3
2026-07-31T23:35:25Z [SERVER] INFO: Uptime Kuma Version: 2.4.0
2026-07-31T23:35:26Z [SETUP-DATABASE] INFO: Starting Setup Database
2026-07-31T23:35:26Z [SETUP-DATABASE] INFO: Listening on:
2026-07-31T23:35:26Z [SETUP-DATABASE] INFO: -  http://localhost:3001
2026-07-31T23:35:26Z [SETUP-DATABASE] INFO: Waiting for user action...

Die Datenbank legt Kuma noch nicht an – es wartet bewusst auf deine Auswahl im Browser. Ruf dazu https://status.DEINE_DOMAIN auf. Uptime Kuma 2.x fragt zuerst die Datenbank ab – für ein Setup wie unseres ist SQLite die richtige, einfachste Wahl (auswählen, auf Weiter klicken). Direkt danach legst du das Admin-Konto an (Benutzername + starkes Passwort).

Schritt 3: Den ersten Monitor anlegen

Ein Monitor ist eine wiederkehrende Prüfung. Klicke auf Neuen Monitor hinzufügen und lege einen für Traefik selbst an:

• Monitortyp: HTTP(s)
• Anzeigename: Traefik Dashboard
• URL: https://traefik.DEINE_DOMAIN
• Heartbeat-Intervall: 60 Sekunden
• Authentifizierung: Das Traefik-Dashboard ist per Basic-Auth geschützt (Schritt 7 des Traefik-Tutorials) – wähle deshalb ganz unten im Abschnitt Authentifizierung unter Methode den Eintrag HTTP-Basic-Auth und trage Benutzer und Passwort ein. Ohne Zugangsdaten bekommt Kuma nur 401 und meldet den Monitor als Down.

Speichern – nach wenigen Sekunden steht der Monitor auf Online (grün) und zeigt die Antwortzeit.

Neben dem einfachen HTTP(s)-Check lohnt es sich, den passenden Monitortyp zu wählen:

• HTTP(s) - Schlüsselwort: prüft zusätzlich, ob ein bestimmtes Wort im Antworttext steht. So erkennst du „Server antwortet zwar, zeigt aber eine Fehlerseite".
• TCP Port: für Dienste ohne Web-Oberfläche (z. B. eine Datenbank, ein SSH-Port). Prüft nur, ob der Port offen ist.
• Ping: einfachster Erreichbarkeitstest per ICMP.
• Docker-Container: prüft direkt den Container-Status über den Docker-Socket – praktisch für interne Dienste ohne eigene Domain.
• Push: hier ruft der überwachte Dienst Kuma regelmäßig an. Ideal für Cronjobs und Backups: meldet sich das Skript nicht rechtzeitig, schlägt Kuma Alarm („Dead man’s switch").

Lege für jeden wichtigen Dienst den passenden Monitor an.

Beim HTTP(s)-Monitor lohnt sich zusätzlich die Option „Benachrichtigung bei Zertifikatsablauf" (im Abschnitt Erweitert): Kuma warnt dann rechtzeitig, bevor ein TLS-Zertifikat ausläuft. Bei Diensten hinter Traefik erneuert Let’s Encrypt zwar automatisch – aber genau dieser Automatismus fällt gelegentlich leise aus (ein DNS-Record wird geändert, Port 80 versehentlich zugemacht). Der Monitor ist dein Sicherheitsnetz und meldet sich, solange noch Tage zum Reparieren bleiben, statt dass Besucher plötzlich vor einer Zertifikatswarnung stehen.

Schritt 4: Benachrichtigungen einrichten (E-Mail und Telegram)

Ein Monitor ohne Alarm ist nur ein hübsches Diagramm. Unter Einstellungen → Benachrichtigungen → Benachrichtigung einrichten legst du einen Kanal an. Uptime Kuma unterstützt über 90 – wir richten die zwei häufigsten komplett ein: E-Mail für die klassische Nachricht und Telegram für Push direkt aufs Handy.

E-Mail (SMTP)

Wähle als Benachrichtigungstyp „E-Mail (SMTP)" und trage die Daten deines Mailanbieters ein:

• Hostname / Port: z. B. smtp.DEIN_ANBIETER.de und 587
• Sicherheit: genau zwei Einträge zur Auswahl – Keine / STARTTLS (25, 587) für Port 587 (Kuma handelt STARTTLS selbst aus) und TLS (465) für Port 465
• Benutzername / Passwort: deine SMTP-Zugangsdaten
• Absender-E-Mail / An E-Mail: von welcher Adresse die Warnung kommt und an welche sie geschickt wird

Klick auf Testen – innerhalb weniger Sekunden landet eine Testnachricht im Postfach. Erst wenn die wirklich ankommt, stimmen Zugangsdaten und Port. Speichern nicht vergessen.

Telegram

Telegram ist ideal für sofortige Push-Alarme aufs Handy – ohne eigenen Mailserver. Du brauchst zwei Angaben:

1. Bot-Token: Schreib in Telegram @BotFather an, sende /newbot, vergib einen Namen – BotFather antwortet mit dem Token.
2. Chat-ID: Schreib deinem neuen Bot eine beliebige Nachricht, ruf dann https://api.telegram.org/bot<DEIN_TOKEN>/getUpdates im Browser auf und lies die chat.id aus der Antwort.

Trage Token und Chat-ID in die Telegram-Benachrichtigung ein (Uptime Kuma verlinkt beide Hilfen direkt im Dialog) und klick Testen – die Nachricht sollte sofort im Chat erscheinen.

Willst du Push-Nachrichten komplett in Eigenregie (ohne Telegram-Server), nimm ntfy – selbst gehostet, mit eigenem Rezept in der Serie. Kuma kennt es als eingebauten Benachrichtigungstyp Ntfy.

Schritt 5: Eine öffentliche Status-Seite (optional)

Kuma kann eine Status-Seite veröffentlichen, auf der Besucher sehen, ob deine Dienste laufen. So gehst du vor:

1. Statusseiten → Neue Statusseite, dann Name (z. B. „Serverküche Status") und Slug (die URL, z. B. serverkueche) vergeben und auf Weiter klicken.
2. Im Editor Gruppe hinzufügen (z. B. „Dienste"), darunter über das Auswahlfeld die gewünschten Monitore hinzufügen.
3. Oben rechts Speichern – fertig. Öffentlich erreichbar ist die Seite dann unter https://status.DEINE_DOMAIN/status/serverkueche.

Nimm nur auf, was wirklich jeder sehen darf – interne Dienste besser weglassen.

Schritt 6: Fehlalarme vermeiden – das Alarm-Verhalten feinjustieren

Ein Monitor, der bei jedem kurzen Netzwerk-Schluckauf Alarm schlägt, wird schnell ignoriert – und dann verpasst du den echten Ausfall. Im Monitor-Formular stellst du das Verhalten passend ein:

• Wiederholungen: Erst nach n fehlgeschlagenen Prüfungen gilt der Dienst als „Down". 2–3 filtert einzelne Aussetzer heraus, ohne echte Ausfälle lange zu verschleiern.
• Heartbeat-Wiederholungsintervall: Kuma darf im Fehlerfall häufiger prüfen (z. B. alle 20 Sekunden), um die Erholung schnell zu erkennen. Das Feld taucht erst auf, sobald Wiederholungen größer als 0 ist.
• Benachrichtigung erneut senden nach X aufeinanderfolgenden Ausfällen: Kuma erinnert dich alle X fehlgeschlagenen Prüfungen erneut, solange ein Dienst down ist – nützlich, damit ein Ausfall nachts nicht in einer einzigen Mail untergeht. 0 schaltet das Wiederholen ab.

Schritt 7: Cronjobs überwachen mit einem Push-Monitor

Klassische Monitore prüfen von außen, ob ein Dienst antwortet. Für Dinge, die still im Hintergrund laufen – ein nächtliches Backup, ein Sync-Skript, ein Cronjob – dreht der Push-Monitor das Prinzip um: Nicht Kuma fragt an, sondern dein Skript meldet sich. Bleibt die Meldung aus, schlägt Kuma Alarm – der klassische „Dead man’s switch".

Lege einen Monitor vom Typ Push an. Kuma zeigt dir dann eine eindeutige Push-URL:

https://status.DEINE_DOMAIN/api/push/DEIN_TOKEN?status=up&msg=OK&ping=

Diese URL rufst du am Ende deines Skripts auf – zum Beispiel nach einem erfolgreich durchgelaufenen Backup:

# ... dein Backup-Befehl ...
curl -fsS "https://status.DEINE_DOMAIN/api/push/DEIN_TOKEN?status=up&msg=Backup+OK" > /dev/null

Stell das Prüfintervall in Kuma etwas großzügiger ein als deinen Cron-Takt (läuft das Backup stündlich, gib Kuma z. B. 90 Minuten Toleranz). Kommt in dieser Zeit kein curl, geht der Monitor auf Down und du wirst benachrichtigt – du erfährst also von einem nicht gelaufenen Backup, nicht erst, wenn du es dringend brauchst.

Schritt 8: Den Admin-Login mit 2FA absichern

Dein Kuma-Login schützt den Zugang zu allen Monitoren, den hinterlegten Benachrichtigungs-Zugangsdaten und der Status-Seiten-Konfiguration – und er hängt öffentlich im Netz. Schalte deshalb Zwei-Faktor-Authentifizierung ein: unter Einstellungen → Sicherheit → Zwei-Faktor-Authentifizierung → 2FA-Einstellungen. Kuma fragt zuerst dein aktuelles Passwort ab; nach 2FA aktivieren erscheint der QR-Code, den du mit einer Authenticator-App (z. B. Aegis oder 2FAS) scannst. Gib den erzeugten Code ein, klick Token verifizieren und danach Speichern – ohne diesen letzten Klick bleibt 2FA inaktiv.

Wenn es nicht funktioniert

Wartung & Backups

• Sichern: Das komplette Herz von Kuma ist das Volume kuma-data (eine SQLite-Datenbank). Sichere es regelmäßig – ist es weg, sind alle Monitore und die Historie weg. Das Off-Site-Backup dafür bauen wir im Restic-Tutorial.
• Updates: Tag :2 bleibt bei der 2.x-Reihe und bringt Fehlerbehebungen mit docker compose pull && docker compose up -d. Vor einem Sprung auf eine neue Hauptversion (z. B. später :3) die Release-Notes lesen und vorher das Volume sichern.
• Von 1.x kommend? Der Wechsel auf :2 migriert die SQLite-Datenbank beim ersten Start automatisch – das kann einen Moment dauern, und ein Zurück auf :1 ist danach nicht vorgesehen. Sichere deshalb vorher das kuma-data-Volume, dann bist du auf der sicheren Seite. Neu-Installationen (wie oben) betrifft das nicht.
• Ehrliche Einschränkung: Ein Monitor, der auf demselben Server läuft wie die überwachten Dienste, kann dich nicht warnen, wenn der ganze Server ausfällt – dann ist auch Kuma offline. Ergänze für den Ernstfall einen externen Wächter. Zwei günstige Wege: ein zweites Uptime Kuma auf einem kleinen Server (oder zu Hause), das nur diese Instanz per HTTP überwacht – oder ein kostenloser externer Ping-Dienst, der deine öffentliche Status-Seite anpingt. So bekommst du auch dann eine Meldung, wenn der ganze Host weg ist – der einzige Fall, den ein lokaler Monitor prinzipbedingt nicht abdecken kann.

Damit hast du das App-Muster verinnerlicht und überwachst ab sofort alles, was du hinter Traefik hängst. Was jede weitere App voraussetzt, sind verschlüsselte Off-Site-Backups mit Restic – damit deine Daten einen Servercrash überleben.