Zum Inhalt springen
Serverküche
Suche

Die Suche wird geladen …

Anwendungen Schwierigkeit: Fortgeschritten

Healthchecks: Cron-Jobs & Backups überwachen (Dead-Man-Switch)

Merkt, wenn ein Backup NICHT läuft: Healthchecks überwacht Cron-Jobs per Dead-Man-Switch und alarmiert bei Ausfall – selbst gehostet hinter Traefik.

· Zuletzt aktualisiert: · 9 Min. Lesezeit ·Dauer: ca. 45 Minuten
Inhaltsverzeichnis

Die gefährlichsten Ausfälle sind die stillen: Das nächtliche Backup läuft seit drei Wochen nicht mehr – und niemand merkt es, bis man die Daten wirklich braucht. Uptime Kuma sagt dir, wenn ein Dienst da ist. Healthchecks sagt dir, wenn ein Job nicht gelaufen ist. Genau das ist der Unterschied, der Daten rettet.

Was bauen wir?

Einen selbst gehosteten Healthchecks-Server (v5.0.3) hinter Traefik, der als Dead-Man-Switch funktioniert: Jeder überwachte Job „meldet sich“ nach erfolgreichem Lauf mit einem kurzen HTTP-Ping. Bleibt dieser Ping aus (weil der Job abgestürzt ist, der Server aus war oder der Cron-Eintrag fehlt), schlägt Healthchecks Alarm. Am Ende überwachst du damit deine Restic-Backups, Datenbank-Dumps und jeden anderen wiederkehrenden Job – und wirst benachrichtigt, bevor das Fehlen auffällt.

Voraussetzungen

🍳 Empfehlung Anzeige

VPS 1000 G12.5

4 vCore · 8 GB RAM · 128 GB SSD

ab 14,50 €/Monat

Healthchecks ist genügsam und läuft gut neben deinem übrigen Stack.

Zu netcup →

💶 1 Monat gratis:

Einmal einlösbar, gilt für VPS 1000 G12.5. Im Warenkorb einlösen →

💶 5,95 € Gutschein für netcup-Neukunden: immer gültig · nicht für Domains und VPS Lite

Alle netcup-Gutscheine →

Schritt für Schritt

Schritt 1: Das Prinzip verstehen – ein umgedrehtes Monitoring

Klassisches Monitoring fragt aktiv: „Antwortet der Dienst?“ Healthchecks dreht das um: Der Job meldet sich beim Server. Jeder Check hat eine eindeutige Ping-URL. Nach erfolgreichem Lauf ruft der Job diese URL auf. Healthchecks erwartet den Ping in einem festgelegten Zeitfenster (Period) plus einer Toleranz (Grace Time). Kommt der Ping nicht rechtzeitig, gilt der Check als „down“ und Healthchecks alarmiert. Das ist der Dead-Man-Switch: Nicht das Vorhandensein eines Signals löst Alarm aus, sondern sein Ausbleiben.

Schritt 2: Compose-Datei anlegen

Healthchecks ist eine Django-Anwendung; wir betreiben sie mit SQLite – für den typischen Selfhosting-Umfang völlig ausreichend. Lege das Projekt an:

Terminal
mkdir -p /opt/healthchecks/data && cd /opt/healthchecks
chown -R 1000:1000 data

Die compose.yaml – ersetze DEINE_DOMAIN und erzeuge einen eigenen SECRET_KEY (openssl rand -hex 32):

YAML
services:
  healthchecks:
    image: healthchecks/healthchecks:v5.0.3
    restart: unless-stopped
    user: "1000:1000"
    volumes:
      - ./data:/data
    environment:
      SITE_ROOT: https://DEINE_DOMAIN
      SITE_NAME: Serverkueche Healthchecks
      ALLOWED_HOSTS: DEINE_DOMAIN
      DEBUG: "False"
      REGISTRATION_OPEN: "False"
      DB: sqlite
      DB_NAME: /data/hc.sqlite
      SECRET_KEY: "DEIN_ZUFAELLIGER_SCHLUESSEL"
    networks: [proxy]
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.hc.rule=Host(`DEINE_DOMAIN`)"
      - "traefik.http.routers.hc.entrypoints=websecure"
      - "traefik.http.routers.hc.tls.certresolver=le"
      - "traefik.http.services.hc.loadbalancer.server.port=8000"

networks:
  proxy:
    external: true

Bei SQLite ist DB_NAME Pflicht

Ohne DB_NAME: /data/hc.sqlite legt Healthchecks die Datenbank an einer nicht beschreibbaren Stelle an und startet mit „unable to open database file“ nicht.

Ohne REGISTRATION_OPEN steht die Anmeldung für alle offen

Healthchecks setzt REGISTRATION_OPEN intern auf True. Ohne die Zeile oben trägt die Anmeldeseite einen Sign-Up-Knopf, und jeder, der deine Adresse kennt, legt sich selbst ein Konto auf deiner Instanz an. Ein so angelegter Fremd-Account landet tatsächlich in der Datenbank – und zwar auch dann, wenn der Versand der Bestätigungsmail mangels SMTP scheitert. Mit REGISTRATION_OPEN: "False" verschwindet der Knopf, und /accounts/signup/ antwortet mit 403 Forbidden.

Schritt 3: Starten und anmelden

Terminal
docker compose up -d

Das Image bringt einen Healthcheck mit; Traefik leitet erst weiter, wenn der Container healthy ist – das dauert nur wenige Sekunden. Prüfe:

Terminal
docker compose ps --format 'table {{.Name}}\t{{.Image}}\t{{.Status}}'
Ausgabe
NAME                          IMAGE                              STATUS
healthchecks-healthchecks-1   healthchecks/healthchecks:v5.0.3   Up 42 seconds (healthy)

Beim Start prüft Healthchecks, ob der Hostname aus SITE_ROOT in ALLOWED_HOSTS steht. Fehlt er dort, bricht der Container mit dem Fehler hc.api.E002 ab und hängt als Restarting in einer Neustartschleife – Traefik findet keinen laufenden Dienst, und deine Domain liefert nur ein Traefik-404. Beide Variablen müssen also denselben Hostnamen tragen, ALLOWED_HOSTS dabei ohne https://.

Ein Konto bringt Healthchecks nicht von selbst mit – das Image legt beim Start nur die Datenbank an. Leg deinen Zugang deshalb einmalig selbst an (Passwort ersetzen):

Terminal
docker compose exec healthchecks python manage.py createsuperuser \
  --email admin@DEINE_DOMAIN --password DEIN_STARKES_PASSWORT
Ausgabe
System check identified some issues:

WARNINGS:
?: (hc.api.W002) No SMTP configuration, cannot send email
	HINT: See https://github.com/healthchecks/healthchecks#sending-emails
?: (mail.W001) Your MAILERS setting has no 'default' entry. Sending email without a valid mailer will fail.
	HINT: Add a 'default' entry to MAILERS.
Superuser created successfully.

Die beiden Warnungen sind hier normal: Es ist noch kein Mailserver hinterlegt. Das holst du in Schritt 7 nach – fürs Anlegen des Kontos spielt es keine Rolle.

SUPERUSER_EMAIL wirkt nicht

In vielen Anleitungen stehen SUPERUSER_EMAIL und SUPERUSER_PASSWORD als Umgebungsvariablen in der Compose-Datei. Das offizielle Image liest sie nicht – sein Startskript führt vor dem Start der Dienste nur manage.py migrate aus. Wer sich darauf verlässt, steht vor einer Anmeldeseite, an der kein Konto existiert. Der Weg über createsuperuser oben ist der verlässliche.

Öffne jetzt https://DEINE_DOMAIN/ und melde dich mit diesen Zugangsdaten an:

Die Anmeldeseite von Healthchecks unter der eigenen HTTPS-Domain
Der selbst gehostete Healthchecks-Login – ohne Sign-Up-Knopf, weil REGISTRATION_OPEN auf False steht

Schritt 4: Ein Projekt und den ersten Check anlegen

Nach dem Login legst du über New Project… ein Projekt an (z. B. „Serverküche“) und darin über Add Check deinen ersten Check. Gib ihm einen sprechenden Namen, Tags und einen Zeitplan – Period = erwarteter Abstand zwischen zwei Läufen (für ein tägliches Backup: 1 Tag), Grace Time = wie lange Healthchecks nach dem Fälligkeitszeitpunkt noch wartet, bevor es Alarm schlägt (z. B. 1 Stunde). Die Übersicht zeigt alle Checks mit Status, Ping-URL und letztem Ping:

Die Healthchecks-Übersicht mit mehreren Checks, Ping-URLs und Status-Anzeige
Die Check-Übersicht: grüner Haken für „läuft“, dazu Ping-URL, Zeitplan und letzter Ping

Jeder Check bekommt eine eigene Ping-URL der Form https://DEINE_DOMAIN/ping/<UUID>. Ein Klick auf den Check öffnet die Detailseite mit Anleitung, Verlauf und Status:

Die Detailseite eines Checks mit Ping-URL, aktuellem Status „up“ und Ereignisprotokoll
Die Detailseite: Ping-URL, aktueller Status und das Protokoll der eingegangenen Pings

Schritt 5: Einen Job den Ping senden lassen

Jetzt der Kern. Deinen Job lässt du nach erfolgreichem Lauf die Ping-URL aufrufen. Das einfachste Beispiel – am Ende deines Skripts:

Terminal
curl -fsS -m 10 --retry 5 https://DEINE_DOMAIN/ping/DEINE_CHECK_UUID

-fsS macht curl leise, aber meldet Fehler; -m 10 bricht nach 10 Sekunden ab; --retry 5 fängt kurze Netzwerkaussetzer ab. Noch besser: den Exit-Code des Jobs mitmelden, damit ein fehlgeschlagener Lauf sofort als Fehler erscheint statt als „kein Ping“:

Terminal
#!/bin/bash
URL="https://DEINE_DOMAIN/ping/DEINE_CHECK_UUID"
# ... hier läuft dein eigentlicher Job ...
restic backup /wichtige/daten
# Exit-Code an Healthchecks melden (0 = ok, sonst Fehler)
curl -fsS -m 10 --retry 5 "$URL/$?"

Schritt 6: Restic-Backups überwachen

Das ist der Paradefall. Wenn deine Restic-Backups per systemd-Timer laufen, ergänzt du den Ping am Ende des Backup-Skripts. Läuft das Backup nicht (Timer deaktiviert, Server aus, Skript abgestürzt), bleibt der Ping aus – und nach Ablauf der Grace Time alarmiert Healthchecks. So erfährst du von einem toten Backup nach Stunden, nicht erst beim Datenverlust.

Start- und Fehlersignale nutzen

Healthchecks kann mehr als „fertig“: Ein Ping auf .../ping/UUID/start vor dem Job misst zusätzlich die Laufzeit, ein Ping auf .../ping/UUID/fail meldet aktiv einen Fehlschlag. So siehst du nicht nur ob, sondern auch wie lange ein Job lief – nützlich, um schleichend langsamer werdende Backups zu erkennen.

Schritt 7: Benachrichtigungen einrichten

Ein Alarm nützt nur, wenn er dich erreicht. Unter Integrations verbindest du Kanäle: E-Mail, ntfy, Gotify, Webhooks und viele mehr. Für den Selfhosting-Stack ist ntfy die naheliegende Wahl – Push aufs Handy, ohne fremden Dienst. Richte mindestens einen Kanal ein und weise ihn deinen Checks zu, sonst bleibt der „down“-Status stumm.

Willst du zusätzlich per E-Mail alarmiert werden, fehlen dem Image noch die Zugangsdaten deines Mailservers. Die gehören in den environment-Block der compose.yaml:

YAML
      EMAIL_HOST: mail.DEINE_DOMAIN
      EMAIL_PORT: "587"
      EMAIL_HOST_USER: DEIN_SMTP_BENUTZER
      EMAIL_HOST_PASSWORD: DEIN_SMTP_PASSWORT
      EMAIL_USE_TLS: "True"
      DEFAULT_FROM_EMAIL: healthchecks@DEINE_DOMAIN

Nach docker compose up -d prüfst du, ob Healthchecks die Einstellungen annimmt:

Terminal
docker compose exec healthchecks python manage.py check
Ausgabe
System check identified no issues (0 silenced).

Fehlt EMAIL_HOST, meldet derselbe Befehl stattdessen (hc.api.W002) No SMTP configuration, cannot send email – und ein Versand über manage.py sendtestemail bricht mit MailerDoesNotExist: "The mailer 'default' is not configured." ab.

Auf einem netcup-Server ist SMTP zunächst dicht

netcup weist neuen Servern standardmäßig die Policy „netcup Mail block“ zu, die ausgehend die Ports 25, 465 und 587 sperrt. Healthchecks meldet dann keinen Fehler in der Konfiguration – der Versand läuft einfach in einen Timeout. Die Policy nimmst du dem Server im SCP selbst ab, siehe netcup-Firewall einrichten. Wer das nicht will, bleibt bei ntfy: Das läuft über HTTPS und ist von der Sperre nicht betroffen.

Wenn es nicht funktioniert

Container startet nicht: „unable to open database file“. DB_NAME: /data/hc.sqlite fehlt oder der data-Ordner gehört nicht UID 1000. Pfad setzen und chown -R 1000:1000 /opt/healthchecks/data (siehe Warnung in Schritt 2).

Der Container steht auf Restarting, die Domain liefert 404. In docker compose logs steht (hc.api.E002) The hostname in settings.SITE_ROOT is not found in settings.ALLOWED_HOSTS. Trag in ALLOWED_HOSTS exakt den Hostnamen aus SITE_ROOT ein – ohne https:// – und starte mit docker compose up -d neu.

Login schlägt mit 403 fehl (CSRF-Fehler beim Absenden). Healthchecks hält die Anfrage dann für unverschlüsseltes HTTP, und Django lehnt das Formular ab, weil die Herkunft https://… nicht dazu passt. Das Image erkennt HTTPS am Header X-Forwarded-Proto, den Traefik mitschickt – fehlt er, etwa hinter einem anders konfigurierten Proxy, kommt dieser Fehler. Eine Variable CSRF_TRUSTED_ORIGINS hilft nicht: Healthchecks liest sie nicht aus.

Der Check wird nicht „grün“, obwohl der Job läuft. Prüfe, ob der curl-Ping wirklich ausgeführt wird und die richtige UUID trifft: curl -v https://DEINE_DOMAIN/ping/UUID sollte OK zurückgeben. Auf der Detailseite siehst du im Protokoll, ob und von welcher IP Pings ankommen.

Ich bekomme keine Benachrichtigung bei „down“. Es ist kein Integrations-Kanal zugewiesen, oder (bei E-Mail) fehlen die SMTP-Einstellungen. Unter „Integrations“ einen Kanal einrichten und dem Check zuweisen.

Dein Problem ist nicht dabei? Alle Fehlermeldungen durchsuchen →

Wartung & Backups

  • Updates. Setze den Image-Tag (healthchecks/healthchecks:v5.0.3) gelegentlich auf die aktuelle Version und docker compose up -d; die Datenbank migriert beim Start automatisch. Seit v5.0 läuft im Image gunicorn statt uWSGI – wer in seiner Compose ein eigenes command: mit uwsgi stehen hat, stellt es auf /opt/healthchecks/run.sh um; die Datei aus diesem Tutorial braucht keine Änderung. Den Rest übernimmt dein normaler Update-Prozess.
  • Backup. Der gesamte Zustand liegt in der SQLite-Datei unter data/ – ins Restic-Backup aufnehmen. Kleiner, aber feiner Nebeneffekt: Healthchecks überwacht dann das Backup, das es selbst mitsichert – schließe den Kreis, indem der Backup-Job auch einen Healthchecks-Check pingt.
  • Wer überwacht den Wächter? Healthchecks selbst sollte laufen, wenn es alarmieren soll. Ergänze es deshalb in Uptime Kuma als HTTP-Monitor – so decken sich die beiden Werkzeuge gegenseitig ab: Kuma prüft, dass Healthchecks erreichbar ist, Healthchecks prüft, dass deine Jobs gelaufen sind.

Feedback per E-Mail: feedback@serverkueche.de

Das könnte dir auch schmecken