Cronjobs mit Healthchecks per Docker überwachen¶
Veröffentlicht am 27. August 2026 · Geschätzte Lesezeit: 5 Minuten
Backups und Wartungsskripte können unbemerkt ausfallen. Healthchecks arbeitet wie ein Totmannschalter: Nach einem erfolgreichen Lauf ruft der Job eine persönliche Ping-Adresse auf. Bleibt der Ping aus, wird der Check als gestört markiert und kann eine Benachrichtigung auslösen. Die lokale Installation mit Docker Compose dauert ungefähr 20 Minuten.
Voraussetzungen
- Ein Server mit Docker Engine und Docker Compose
- Port 8000/TCP im Heimnetz frei
git,curlund ein Texteditor auf dem Server- Für Benachrichtigungen die Zugangsdaten eines SMTP-Kontos
1. Projekt herunterladen¶
Führe die Befehle auf dem Docker-Server aus. Sie laden das offizielle Repository und wechseln in dessen Docker-Ordner:
Das Repository enthält die vom Projekt gepflegte Compose-Datei und eine Beispielkonfiguration.
2. Konfiguration anlegen¶
Kopiere die offizielle Beispieldatei:
Erzeuge zwei zufällige Werte. Kopiere die Ausgaben nur in deine lokale .env und veröffentliche sie nicht:
Öffne anschließend die Datei:
Passe mindestens die folgenden Zeilen an. Ersetze <server-ip> durch die feste IP des Servers, <db-passwort> durch die erste Zufallsausgabe, <secret-key> durch die zweite Ausgabe und <absender-adresse> durch eine gültige Absenderadresse:
ALLOWED_HOSTS=<server-ip>,localhost
DB=postgres
DB_HOST=db
DB_NAME=hc
DB_PASSWORD=<db-passwort>
DB_PORT=5432
DB_USER=postgres
DEBUG=False
DEFAULT_FROM_EMAIL=<absender-adresse>
REGISTRATION_OPEN=False
SECRET_KEY=<secret-key>
SITE_ROOT=http://<server-ip>:8000
Geheimnisse schützen
Die Werte für DB_PASSWORD und SECRET_KEY sind Zugangsdaten. Sichere die Datei nur lokal, setze keine Beispielwerte ein und lade sie niemals in ein öffentliches Repository hoch.
Beschränke die Leserechte der Datei auf deinen Benutzer:
3. Fertiges Container-Image verwenden¶
Die offizielle Compose-Datei baut Healthchecks normalerweise aus dem heruntergeladenen Quellcode. Für eine einfachere Installation öffnest du sie:
Entferne beim Dienst web den Block build: mit seinen eingerückten Unterzeilen und aktiviere stattdessen die bereits vorbereitete Image-Zeile. Der betreffende Abschnitt muss danach so aussehen:
web:
image: healthchecks/healthchecks:latest
env_file:
- .env
ports:
- "8000:8000"
depends_on:
- db
command: bash -c 'while !</dev/tcp/db/5432; do sleep 1; done; uwsgi /opt/healthchecks/docker/uwsgi.ini'
Die übrigen Teile der offiziellen Compose-Datei, besonders der Dienst db und das Volume db-data, bleiben unverändert.
Prüfe die zusammengeführte Compose-Konfiguration. Der Befehl muss ohne Fehlermeldung enden:
4. Container starten¶
Lade die Images und starte Datenbank sowie Webanwendung im Hintergrund:
Prüfe den Zustand:
Bei Problemen zeigen die letzten 100 Protokollzeilen meist die Ursache:
5. Administratorkonto anlegen¶
Der folgende offizielle Verwaltungsbefehl fragt interaktiv nach E-Mail-Adresse und Passwort. Führe ihn im Ordner healthchecks/docker aus:
Öffne danach http://<server-ip>:8000 und melde dich an. Ersetze <server-ip> durch die Server-IP.
Nicht unverschlüsselt ins Internet stellen
Port 8000 ist für den Zugriff im vertrauenswürdigen Heimnetz gedacht. Für externen Zugriff brauchst du einen Reverse Proxy mit HTTPS. Er muss X-Forwarded-For und X-Forwarded-Proto selbst korrekt setzen und von Besuchern gelieferte Werte überschreiben. Eine einfache Portfreigabe im Router ist nicht sicher.
6. Ersten Check erstellen¶
Klicke in Healthchecks auf Add Check, vergib einen Namen wie NAS-Backup und stelle Zeitplan sowie Karenzzeit passend zum Job ein. Kopiere danach die angezeigte Ping-URL. Sie enthält eine geheime UUID und sieht ungefähr so aus:
Ersetze <server-ip> durch die Server-IP und <check-uuid> durch die ausschließlich für diesen Check erzeugte UUID.
Ping-URL wie ein Geheimnis behandeln
Wer die URL kennt, kann einen erfolgreichen Lauf vortäuschen. Veröffentliche sie deshalb nicht in Anleitungen oder öffentlichen Skript-Repositories.
7. Cronjob anbinden¶
Öffne die Crontab des Benutzers, unter dem das eigentliche Skript läuft:
Das folgende Beispiel startet täglich um 03:00 Uhr ein Backup und sendet nur bei erfolgreichem Abschluss einen Ping. Ersetze <pfad-zum-skript>, <server-ip> und <check-uuid>:
0 3 * * * <pfad-zum-skript> && curl -fsS -m 10 --retry 5 -o /dev/null http://<server-ip>:8000/ping/<check-uuid>
Durch && wird der Ping nur ausgeführt, wenn das Skript mit Exitcode 0 endet. curl wartet höchstens 10 Sekunden und wiederholt vorübergehende Fehler bis zu fünfmal.
8. Benachrichtigungen aktivieren¶
Für E-Mail-Benachrichtigungen ergänze in .env die Daten deines SMTP-Anbieters. Ersetze alle spitzen Platzhalter; die Werte unterscheiden sich je nach Anbieter:
EMAIL_HOST=<smtp-server>
EMAIL_HOST_PASSWORD=<smtp-passwort>
EMAIL_HOST_USER=<smtp-benutzer>
EMAIL_PORT=587
EMAIL_USE_TLS=True
Starte nur den Webcontainer neu, damit die Werte eingelesen werden:
Richte die E-Mail-Integration anschließend in der Healthchecks-Oberfläche ein und sende eine Testbenachrichtigung.
9. Backup und Rückweg¶
Die Prüfdaten liegen im benannten Docker-Volume der PostgreSQL-Datenbank. Erzeuge vor Updates eine logische Sicherung. <db-passwort> wird hier nicht in den Befehl geschrieben; PostgreSQL verwendet die Container-Konfiguration:
Sichere zusätzlich .env und docker-compose.yml an einem geschützten Ort. Zum vollständigen Stoppen ohne Datenverlust verwendest du:
Volume nicht versehentlich löschen
Verwende nicht docker compose down -v. Die Option -v löscht das Datenbank-Volume und damit die gespeicherten Checks.
10. Quellen und Stand¶
Die Anleitung wurde am 27. August 2026 mit der offiziellen Dokumentation und den aktuellen Projektdateien abgeglichen:
- Healthchecks: Running with Docker
- Healthchecks: Cronjobs überwachen
- Offizielles Healthchecks-Repository
Fertig¶
Healthchecks läuft jetzt im Heimnetz und erwartet den Ping deines Cronjobs. Starte das Skript einmal manuell und prüfe in der Oberfläche, ob der Check auf Up wechselt. Bleibt ein späterer Ping aus, wird der Check nach Ablauf seiner Karenzzeit als gestört markiert.