serverkueche.de

Posted on Jul 19 • Edited on Jul 20 • Originally published at serverkueche.de

Uptime Kuma installieren: Server-Monitoring hinter Traefik

#german #monitoring #uptime #selfhosting

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).

⚠️ Sofort das Admin-Konto anlegen

Solange kein Admin-Konto existiert, kann jeder, der die Seite aufruft, eines
anlegen. Erledige das direkt nach dem ersten Start – nicht „später".

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.

💡 Tipp

Prüfe öffentliche Dienste über ihre echte Domain (https://…), nicht über
localhost. So testest du zugleich, dass Traefik und das Zertifikat von außen
funktionieren – nicht nur, dass der Container läuft.

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 ist ideal für sofortige Push-Alarme aufs Handy – ohne eigenen Mailserver.
Du brauchst zwei Angaben:

Bot-Token: Schreib in Telegram @BotFather an, sende /newbot, vergib einen Namen – BotFather antwortet mit dem Token.
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.

⚠️ Sonst bleibt der Alarm stumm

Eine eingerichtete Benachrichtigung greift nicht automatisch. Aktiviere sie in
jedem Monitor (Häkchen im Monitor-Formular) oder schalte im Benachrichtigungs-Dialog
„Standardmäßig aktiviert" ein und „Auf alle existierenden Monitore anwenden".

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:

Statusseiten → Neue Status-Seite, dann Name (z. B. „Serverküche Status") und Slug (die URL, z. B. serverkueche) vergeben und auf Weiter klicken.
Im Editor Gruppe hinzufügen (z. B. „Dienste"), darunter über das Auswahlfeld die gewünschten Monitore hinzufügen.
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.

💡 Wartungsfenster einplanen

Planst du ein Update mit Downtime, lege unter Wartung ein Wartungsfenster an.
Kuma pausiert dann die Alarme für die betroffenen Monitore – so bekommst du (und die
Status-Seite) keine Fehlalarme, während du selbst am Werk bist.

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.

💡 Wiederherstellung absichern

Bewahre das TOTP-Secret bzw. einen zweiten Authenticator an einem sicheren Ort auf
(Passwortmanager). Verlierst du dein Telefon und hast keine Kopie, kommst du sonst
nur noch über die Datenbank im kuma-data-Volume wieder hinein.

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.

Dieser Beitrag erschien zuerst auf serverkueche.de.

DEV Community