Monitoring mit Uptime Kuma auf Debian 13 — Vollständiger Guide

💡 Hinweis: Dieses Tutorial setzt voraus, dass du einen normalen Benutzer mit sudo-Rechten verwendest — wie im Tutorial Debian 13 Server absichern beschrieben.

1. Einleitung — Was ist Uptime Kuma? Warum Monitoring?

Wer Server, Webseiten oder Dienste betreibt, kennt das Problem: Irgendwann fällt etwas aus — und man erfährt es erst, wenn sich Nutzer beschweren. Monitoring löst dieses Problem, indem es Dienste regelmäßig prüft und bei Ausfällen sofort Alarm schlägt.

Uptime Kuma ist ein modernes, selbst gehostetes Monitoring-Tool mit einer eleganten Web-Oberfläche. Es wurde von Louis Lam entwickelt und bietet:

• 📊 Überwachung von HTTP(S), TCP, Ping, DNS, Docker-Containern, Datenbanken und mehr
• 🔔 Benachrichtigungen über 90+ Kanäle (E-Mail, Telegram, Discord, Slack, Pushover …)
• 📄 Status-Seiten — öffentlich oder passwortgeschützt
• 🔧 Maintenance Windows für geplante Wartungsarbeiten
• 🐳 Einfache Installation per Docker
• 💾 Leichtgewichtig — läuft problemlos auf kleinen VPS

In diesem Tutorial installieren wir Uptime Kuma auf Debian 13 (Trixie) mit Docker Compose, richten einen Nginx-Reverse-Proxy mit SSL ein und konfigurieren das komplette Monitoring-Setup.

2. Voraussetzungen

Bevor wir loslegen, sollten folgende Voraussetzungen erfüllt sein:

• ✅ Debian 13 (Trixie) — frisch installiert oder bestehendes System
• ✅ Docker & Docker Compose — siehe Tutorial #4: Docker auf Debian 13 installieren
• ✅ Nginx Reverse Proxy Manager oder Nginx — siehe Tutorial #6: Nginx Proxy Manager
• ✅ Domain oder Subdomain — z. B. status.example.com, DNS-A-Record auf deinen Server
• ✅ Root-Zugang oder ein Benutzer mit sudo-Rechten

3. Uptime Kuma mit Docker Compose installieren

3.1 Verzeichnisstruktur anlegen

Wir erstellen ein eigenes Verzeichnis für Uptime Kuma:

mkdir -p /opt/uptime-kuma
cd /opt/uptime-kuma

3.2 Docker Compose Datei erstellen

Erstelle die Datei docker-compose.yml:

nano docker-compose.yml

Inhalt:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      - ./data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "3001:3001"
    environment:
      - TZ=Europe/Berlin

3.3 Container starten

docker compose up -d

Prüfe, ob der Container läuft:

docker compose ps

Erwartete Ausgabe:

NAME          IMAGE                      STATUS          PORTS
uptime-kuma   louislam/uptime-kuma:1     Up 30 seconds   0.0.0.0:3001->3001/tcp

Uptime Kuma ist jetzt unter http://DEINE-SERVER-IP:3001 erreichbar.

4. Nginx Reverse Proxy + SSL

Damit Uptime Kuma über HTTPS erreichbar ist, richten wir einen Nginx-Reverse-Proxy ein. Du hast zwei Optionen:

Option A: Nginx Proxy Manager (empfohlen)

Falls du unserem Tutorial #6 gefolgt bist, nutzt du bereits den Nginx Proxy Manager. Dort legst du einfach einen neuen Proxy Host an:

1. Öffne den Nginx Proxy Manager
2. Klicke auf „Add Proxy Host“
3. Trage ein:
   • Domain Names: status.example.com
   • Scheme: http
   • Forward Hostname / IP: uptime-kuma (Container-Name) oder die Server-IP
   • Forward Port: 3001
   • Websockets Support: ✅ aktivieren (wichtig!)
   • Im Tab „SSL“: Let’s Encrypt Zertifikat anfordern
   • Speichern

Option B: Nginx manuell konfigurieren

Falls du Nginx direkt nutzt, erstelle eine Konfigurationsdatei:

nano /etc/nginx/sites-available/uptime-kuma

Inhalt:

server {
    listen 80;
    server_name status.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name status.example.com;

    ssl_certificate /etc/letsencrypt/live/status.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/status.example.com/privkey.pem;

    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;
    }
}

Aktivieren und SSL-Zertifikat holen:

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

Port-Bindung einschränken (optional)

Nachdem der Reverse Proxy steht, kannst du Uptime Kuma nur noch auf localhost lauschen lassen. Ändere in der docker-compose.yml:

ports:
      - "127.0.0.1:3001:3001"

Dann neu starten:

docker compose up -d

5. Erste Schritte: Dashboard & Account

5.1 Admin-Account erstellen

Beim ersten Aufruf von Uptime Kuma wirst du aufgefordert, einen Admin-Account zu erstellen. Wähle:

• Benutzername: Frei wählbar (nicht „admin“!)
• Passwort: Mindestens 12 Zeichen, komplex

5.2 Dashboard-Übersicht

Nach dem Login siehst du das Dashboard mit:

• Linke Sidebar: Liste aller Monitore mit Status-Indikatoren
• Hauptbereich: Details zum ausgewählten Monitor (Uptime-Graph, Response-Time, Logs)
• Oben rechts: Einstellungen, Status-Seiten, Maintenance

5.3 Allgemeine Einstellungen

Unter Settings → General empfehle ich folgende Anpassungen:

• Primary Base URL: https://status.example.com — wird für Links in Benachrichtigungen verwendet
• Sprache: Deutsch (oder Englisch)
• Theme: Auto / Dark / Light nach Geschmack
• Search Engine Visibility: Auf „No“ setzen, wenn die Status-Seite nicht indexiert werden soll

6. Monitore einrichten

Klicke auf „Add New Monitor“, um einen neuen Monitor anzulegen. Uptime Kuma unterstützt zahlreiche Monitor-Typen:

6.1 HTTP(S) Monitor

Der häufigste Typ — prüft, ob eine Webseite erreichbar ist und den erwarteten Statuscode liefert.

Erweiterte Optionen:

• Certificate Expiry Notification: Warnt X Tage vor Ablauf des SSL-Zertifikats
• Max Redirects: Anzahl erlaubter Weiterleitungen
• Keyword: Prüft, ob ein bestimmtes Wort im Response-Body vorkommt
• HTTP Method: GET, POST, PUT, etc.
• Authentication: Basic Auth oder Header-basiert

6.2 TCP Monitor

Prüft, ob ein bestimmter Port erreichbar ist — ideal für Datenbanken, Mail-Server oder andere Dienste.

Monitor Type: TCP Port
Hostname: 192.168.1.100
Port: 5432
Heartbeat Interval: 60

6.3 Ping Monitor

Einfacher ICMP-Ping — prüft die grundlegende Erreichbarkeit eines Hosts.

Monitor Type: Ping
Hostname: 192.168.1.1
Heartbeat Interval: 60

6.4 DNS Monitor

Prüft, ob ein DNS-Record den erwarteten Wert liefert:

Monitor Type: DNS
Hostname: example.com
DNS Resolver Server: 1.1.1.1
Record Type: A
Expected Value: 203.0.113.10

Nützlich, um DNS-Propagierung oder ungewollte Änderungen zu erkennen.

6.5 Docker Container Monitor

Überwacht den Status eines Docker-Containers direkt. Dafür haben wir den Docker-Socket in der Compose-Datei eingebunden.

1. Gehe zu Settings → Docker Hosts
2. Klicke auf „Setup Docker Host“
3. Wähle Connection Type: Socket und Docker Daemon: /var/run/docker.sock
4. Teste die Verbindung und speichere

Danach kannst du einen Monitor erstellen:

Monitor Type: Docker Container
Container Name / ID: nginx-proxy
Docker Host: (der eben angelegte)

6.6 Weitere Monitor-Typen

Uptime Kuma unterstützt außerdem:

• MySQL / PostgreSQL / Redis / MongoDB — Datenbank-Verbindungstests
• gRPC — für Microservice-Architekturen
• Game Server — Steam, Minecraft, etc.
• MQTT — IoT-Broker-Überwachung
• Push — Dein Service meldet sich aktiv bei Uptime Kuma (Dead Man’s Switch)
• JSON Query — Prüft spezifische Werte in einer JSON-API-Antwort

6.7 Monitore organisieren mit Tags und Gruppen

Bei vielen Monitoren wird Ordnung wichtig:

• Tags: Unter Settings → Tags erstellst du farbige Tags (z. B. „Produktion“, „Staging“, „Intern“)
• Gruppen: Im Dashboard kannst du Monitore per Drag & Drop in Gruppen organisieren

7. Benachrichtigungen konfigurieren

Monitoring ohne Benachrichtigungen ist wie ein Rauchmelder ohne Batterie. Unter Settings → Notifications richtest du die Alarmierung ein.

7.1 E-Mail (SMTP)

Klicke auf „Setup Notification“ und wähle Email (SMTP):

Klicke auf „Test“, um eine Testnachricht zu senden.

7.2 Telegram

Telegram ist ideal für schnelle Push-Benachrichtigungen auf dem Handy:

1. Erstelle einen Bot über @BotFather und kopiere den Bot Token
2. Schreibe dem Bot eine Nachricht und ermittle deine Chat ID über https://api.telegram.org/bot<TOKEN>/getUpdates
3. In Uptime Kuma: Notification Type → Telegram
4. Trage Bot Token und Chat ID ein
5. Optional: Gruppe oder Kanal statt persönliche Nachricht

7.3 Discord

Für Team-Monitoring über Discord:

1. In deinem Discord-Server: Kanal-Einstellungen → Integrationen → Webhooks
2. Erstelle einen Webhook und kopiere die Webhook URL
3. In Uptime Kuma: Notification Type → Discord
4. Füge die Webhook URL ein
5. Optional: Bot-Name und Avatar anpassen

7.4 Slack

1. Erstelle eine Incoming Webhook URL in deinem Slack Workspace
2. In Uptime Kuma: Notification Type → Slack
3. Webhook URL einfügen
4. Optional: Channel und Username überschreiben

7.5 Pushover

Pushover liefert native Push-Benachrichtigungen auf iOS und Android:

1. Registriere eine Application auf pushover.net
2. Notiere User Key und API Token
3. In Uptime Kuma: Notification Type → Pushover
4. Keys eintragen und Priorität wählen (Normal, High, Emergency)

7.6 Benachrichtigungen einem Monitor zuweisen

Nachdem du Benachrichtigungskanäle eingerichtet hast, musst du sie den Monitoren zuweisen:

1. Öffne einen Monitor → Edit
2. Scrolle zu Notifications
3. Aktiviere die gewünschten Kanäle
4. Optional: „Default enabled“ aktivieren — dann wird der Kanal automatisch bei neuen Monitoren hinzugefügt

8. Status-Seiten erstellen

Status-Seiten sind öffentlich zugängliche Übersichten über den Zustand deiner Dienste — wie bei status.github.com.

8.1 Status-Seite anlegen

1. Klicke oben im Dashboard auf „Status Pages“
2. Klicke auf „New Status Page“
3. Vergib einen Namen und einen Slug (URL-Pfad, z. B. /status/main)

8.2 Konfiguration

• Logo & Beschreibung: Branding anpassen
• Gruppen: Monitore in logische Gruppen einteilen (z. B. „Webseiten“, „APIs“, „Infrastruktur“)
• Incident erstellen: Manuell einen Incident posten mit Beschreibung und Status
• Custom CSS: Eigenes Styling hinzufügen
• Domain Mapping: Eine eigene Domain direkt auf die Status-Seite zeigen lassen

8.3 Öffentlich vs. Privat

Standardmäßig sind Status-Seiten öffentlich — jeder kann sie ohne Login sehen. Falls du eine private Status-Seite möchtest:

• Verwende den Reverse Proxy, um HTTP Basic Auth vorzuschalten
• Oder schränke den Zugriff per IP-Whitelist ein

9. Maintenance Windows

Geplante Wartungsarbeiten lösen normalerweise Alarme aus. Mit Maintenance Windows verhinderst du das:

9.1 Maintenance erstellen

1. Klicke auf „Maintenance“ im Dashboard
2. „Schedule Maintenance“ wählen
3. Konfiguriere:
   • Titel: z. B. „Server-Update“
   • Beschreibung: Was wird gemacht?
   • Strategie: Einmalig, Wiederkehrend (Cron), oder Täglich
   • Zeitraum: Start- und Endzeit
   • Betroffene Monitore: Welche Monitore pausiert werden

9.2 Strategien

Während eines aktiven Maintenance-Fensters werden betroffene Monitore auf den Status „Under Maintenance“ gesetzt und lösen keine Benachrichtigungen aus. Auf Status-Seiten wird dies ebenfalls angezeigt.

10. API & Automatisierung

Uptime Kuma bietet keine offizielle REST-API, aber es gibt mehrere Wege zur Automatisierung:

10.1 Push-Monitore (Heartbeat API)

Ein Push-Monitor funktioniert wie ein Dead Man’s Switch: Dein Service meldet sich regelmäßig bei Uptime Kuma. Bleibt die Meldung aus, wird alarmiert.

Beim Erstellen eines Push-Monitors erhältst du eine URL wie:

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

Integriere diese in Cronjobs oder Skripte:

# Am Ende eines Backup-Skripts:
curl -s "https://status.example.com/api/push/abc123?status=up&msg=Backup+OK"

# Bei Fehler:
curl -s "https://status.example.com/api/push/abc123?status=down&msg=Backup+FAILED"

10.2 Uptime Kuma API (inoffiziell)

Die Community hat Python- und Node.js-Wrapper für die interne Socket.IO-API erstellt:

• Python: uptime-kuma-api
• Node.js: Über die Socket.IO-Verbindung direkt

Beispiel mit Python:

pip install uptime-kuma-api

from uptime_kuma_api import UptimeKumaApi

api = UptimeKumaApi("https://status.example.com")
api.login("username", "password")

# Alle Monitore auflisten
monitors = api.get_monitors()
for m in monitors:
    print(f"{m['name']}: {m['active']}")

# Neuen Monitor erstellen
api.add_monitor(
    type="http",
    name="Neue Webseite",
    url="https://neue-seite.example.com",
    interval=60
)

api.disconnect()

10.3 Prometheus-Integration

Uptime Kuma kann Metriken im Prometheus-Format exportieren. Aktiviere dies unter Settings → General → Prometheus. Die Metriken sind dann unter /metrics verfügbar.

11. Backup & Restore

Uptime Kuma speichert alle Daten in einer SQLite-Datenbank unter ./data/kuma.db. Ein Backup ist daher einfach:

11.1 Manuelles Backup

# Container stoppen (konsistentes Backup)
cd /opt/uptime-kuma
docker compose stop

# Daten sichern
tar -czf /backup/uptime-kuma-$(date +%Y%m%d).tar.gz ./data/

# Container wieder starten
docker compose start

11.2 Backup über die Web-Oberfläche

Unter Settings → Backup kannst du:

• Export: JSON-Datei mit allen Monitoren, Benachrichtigungen, Status-Seiten und Einstellungen herunterladen
• Import: Eine zuvor exportierte JSON-Datei wiederherstellen

11.3 Automatisches Backup per Cronjob

# /etc/cron.d/uptime-kuma-backup
0 2 * * * root cd /opt/uptime-kuma && docker compose exec -T uptime-kuma cp /app/data/kuma.db /app/data/kuma-backup.db && tar -czf /backup/uptime-kuma-$(date +\%Y\%m\%d).tar.gz -C /opt/uptime-kuma ./data/ && find /backup -name "uptime-kuma-*.tar.gz" -mtime +30 -delete

Dieser Cronjob:

• Erstellt täglich um 2 Uhr ein Backup
• Löscht Backups, die älter als 30 Tage sind

11.4 Restore

# Container stoppen
docker compose stop

# Altes Datenverzeichnis sichern
mv ./data ./data-old

# Backup entpacken
tar -xzf /backup/uptime-kuma-20260217.tar.gz

# Container starten
docker compose start

12. Updates

Updates sind mit Docker Compose denkbar einfach:

cd /opt/uptime-kuma

# Neues Image herunterladen
docker compose pull

# Container mit neuem Image neu starten
docker compose up -d

# Alte Images aufräumen
docker image prune -f

Update-Checkliste:

1. ✅ Backup erstellen (Abschnitt 11)
2. ✅ Release-Notes lesen
3. ✅ docker compose pull
4. ✅ docker compose up -d
5. ✅ Dashboard prüfen — funktioniert alles?
6. ✅ Alte Images aufräumen

13. Zusammenfassung & Checkliste

Hier die komplette Checkliste für dein Uptime-Kuma-Setup:

14. Troubleshooting

Container startet nicht

# Logs prüfen
docker compose logs uptime-kuma

# Häufige Ursachen:
# - Port 3001 bereits belegt → netstat -tlnp | grep 3001
# - Berechtigungsprobleme → chown -R 1000:1000 ./data
# - Speicherplatz voll → df -h

WebSocket-Fehler im Browser

Symptom: Dashboard lädt, aber zeigt keine Live-Updates.

• ✅ Prüfe, ob WebSocket-Support im Reverse Proxy aktiviert ist
• ✅ Die Nginx-Direktiven Upgrade und Connection "upgrade" müssen gesetzt sein
• ✅ Falls Cloudflare im Einsatz: WebSockets sind im Free-Plan unterstützt, aber prüfe die Einstellung

Benachrichtigungen kommen nicht an

• ✅ Testbenachrichtigung über die Oberfläche senden
• ✅ Bei E-Mail: SMTP-Credentials und Port prüfen
• ✅ Bei Telegram: Bot gestartet? (/start an den Bot senden)
• ✅ DNS-Auflösung im Container prüfen: docker exec uptime-kuma nslookup smtp.example.com

Hoher Speicherverbrauch

Die SQLite-Datenbank kann mit vielen Monitoren und langer Historie wachsen:

# Datenbankgröße prüfen
du -sh ./data/kuma.db

# Uptime Kuma hat eine eingebaute Bereinigung unter
# Settings → General → "Keep X days of data"

Backup schlägt fehl

• ✅ Genug Speicherplatz auf dem Backup-Ziel?
• ✅ Berechtigungen prüfen
• ✅ Im Zweifel: Container stoppen vor dem Backup (verhindert DB-Locks)

15. Nächste Schritte

Dein Monitoring mit Uptime Kuma läuft! Hier einige Ideen, wie du es weiter ausbauen kannst:

• 🔗 Prometheus + Grafana: Für detailliertere Dashboards und langfristige Metriken die Prometheus-Integration nutzen
• 🌍 Mehrere Standorte: Installiere Uptime Kuma auf verschiedenen Servern, um regionale Erreichbarkeit zu prüfen
• 🔒 2FA aktivieren: Unter Settings → Security die Zwei-Faktor-Authentifizierung für den Admin-Account einrichten
• 📱 Mobile App: Es gibt inoffizielle Apps für iOS und Android, die sich mit deiner Instanz verbinden
• 🤖 Automatisierung: Mit der Python-API Monitore automatisch aus deiner Infrastruktur-as-Code-Pipeline erstellen

Hast du Fragen oder Probleme? Schreib es in die Kommentare — ich helfe gerne!