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 dieser Zeile – ab hier nimmt der Dienst Anfragen an (Strg+C beendet nur das Mitlesen):

[SERVER] INFO: Welcome to Uptime Kuma
[SERVER] INFO: Uptime Kuma Version: 2.4.0
[SETUP-DATABASE] INFO: Listening on:
[SETUP-DATABASE] INFO: -  http://localhost:3001

Beim ersten Start legt Kuma seine Datenbank im Volume an – das dauert einige Sekunden. Ruf dann https://status.DEINE_DOMAIN im Browser 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)
• Freundlicher Name: Traefik Dashboard
• URL: https://traefik.DEINE_DOMAIN
• Prüfintervall: 60 Sekunden
• Authentifizierung: Das Traefik-Dashboard ist per Basic-Auth geschützt (Schritt 7 des Traefik-Tutorials) – wähle deshalb unten HTTP Basic Auth als Authentifizierungsmethode 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) – Keyword: 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 „Zertifikatsablauf-Benachrichtigung": 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 Benachrichtigungsdienst „E-Mail (SMTP)" und trage die Daten deines Mailanbieters ein:

• Hostname / Port: z. B. smtp.DEIN_ANBIETER.de und 587
• Sicherheit: STARTTLS (Port 587) oder TLS/SSL (Port 465)
• Benutzername / Passwort: deine SMTP-Zugangsdaten
• Absender- / Empfänger-Adresse: von welcher Adresse die Warnung kommt und an welche sie geschickt wird

Klick auf Test – 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 Test – die Nachricht sollte sofort im Chat erscheinen.

Willst du Push-Nachrichten komplett in Eigenregie (ohne Telegram-Server), kommt später ntfy dazu – selbst gehostet, mit eigenem Rezept in der Serie.

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 Status-Seite, 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 (Retries): 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-Intervall bei Ausfall: Kuma darf im Fehlerfall häufiger prüfen (z. B. alle 20 Sekunden), um die Erholung schnell zu erkennen.
• Erneut benachrichtigen: Kuma kann dich alle x Minuten erinnern, solange ein Dienst down ist – nützlich, damit ein Ausfall nachts nicht in einer einzigen Mail untergeht.

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. Kuma zeigt einen QR-Code, den du mit einer Authenticator-App (z. B. Aegis oder 2FAS) scannst; zum Aktivieren gibst du einmal den erzeugten Code ein.

Wenn es nicht funktioniert

Symptom: Bad Gateway (502) beim Aufruf von status.DEINE_DOMAIN.

Ursache & Lösung: Fast immer fehlt das Port-Label traefik.http.services.kuma.loadbalancer.server.port=3001 oder es steht ein falscher Port drin. Traefik erreicht den Container dann zwar, klopft aber am falschen Port an. Label prüfen und docker compose up -d erneut ausführen.

Symptom: 404 page not found statt Kuma.

Ursache & Lösung: Wie bei jeder App hinter Traefik: traefik.enable=true gesetzt? Container im proxy-Netzwerk? Stimmt die Domain in der Host(...)-Regel und zeigt der DNS-Record status.DEINE_DOMAIN auf den Server? Das Traefik-Dashboard zeigt unter „HTTP Routers", ob kuma registriert ist.

Symptom: Die Oberfläche lädt, aber die Live-Aktualisierung ruckelt / bricht ab.

Ursache & Lösung: Kuma nutzt WebSockets. Traefik leitet die standardmäßig korrekt weiter – tritt das Problem trotzdem auf, liegt es meist an einem davorgeschalteten CDN/Proxy (z. B. Cloudflare im „Proxy"-Modus), der WebSockets blockt. Für den Direktbetrieb hinter Traefik ist keine Zusatzkonfiguration nötig.

Symptom: Nach einem Neuaufsetzen sind alle Monitore weg.

Ursache & Lösung: Das kuma-data-Volume wurde gelöscht (z. B. durch docker compose down -v). Alle Konfiguration und Historie liegt allein in diesem Volume – deshalb steht es im nächsten Abschnitt ganz oben.

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.