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.
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
- Ein Server mit laufendem Traefik und Docker Compose
- Eine Subdomain, die auf den Server zeigt – im Folgenden
DEINE_DOMAIN - Wiederkehrende Jobs, die es zu überwachen lohnt (z. B. deine Restic-Backups)
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.
💶 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
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:
mkdir -p /opt/healthchecks/data && cd /opt/healthchecks
chown -R 1000:1000 dataDie compose.yaml – ersetze DEINE_DOMAIN und erzeuge einen eigenen SECRET_KEY (openssl rand -hex 32):
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: trueBei SQLite ist DB_NAME Pflicht
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
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
docker compose up -dDas Image bringt einen Healthcheck mit; Traefik leitet erst weiter, wenn der Container healthy ist – das dauert nur wenige Sekunden. Prüfe:
docker compose ps --format 'table {{.Name}}\t{{.Image}}\t{{.Status}}'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):
docker compose exec healthchecks python manage.py createsuperuser \
--email admin@DEINE_DOMAIN --password DEIN_STARKES_PASSWORTSystem 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
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:

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:

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:

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:
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“:
#!/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
.../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:
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_DOMAINNach docker compose up -d prüfst du, ob Healthchecks die Einstellungen annimmt:
docker compose exec healthchecks python manage.py checkSystem 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
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 unddocker compose up -d; die Datenbank migriert beim Start automatisch. Seit v5.0 läuft im Image gunicorn statt uWSGI – wer in seiner Compose ein eigenescommand:mituwsgistehen hat, stellt es auf/opt/healthchecks/run.shum; 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

Homepage: Dashboard für deine selbstgehosteten Dienste

