Healthchecks¶

Healthchecks ueberwacht Cron-Jobs und geplante Aufgaben per Ping-URL. Jeder Job sendet nach erfolgreicher Ausfuehrung einen HTTP-Ping — bleibt der Ping aus, wird eine Benachrichtigung ausgeloest.

Zugang¶

Parameter	Wert
URL	`https://hc.homelab-external.robinwerner.net`
Port (intern)	8000
Netzwerke	`proxy`, `internal`

Container-Konfiguration¶

Parameter	Wert
Image	`healthchecks/healthchecks:v4.0`
Container-Name	`healthchecks`
Neustart	`unless-stopped`
Netzwerke	`proxy`, `internal`
Abhaengigkeit	`healthchecks-postgres` (healthcheck)

Volumes:

Quelle	Ziel	Beschreibung
`/opt/homelab-data/healthchecks`	`/data`	Anwendungsdaten

Umgebungsvariablen:

Variable	Wert	Beschreibung
`ALLOWED_HOSTS`	`hc.homelab-external.robinwerner.net`	Django Allowed Hosts
`APPRISE_ENABLED`	`True`	Benachrichtigungen via Apprise aktiviert
`DEBUG`	`False`	Produktionsmodus
`DB`	`postgres`	Datenbanktyp
`DB_HOST`	`healthchecks-postgres`	Datenbank-Hostname (internes Netzwerk)
`DB_NAME`	`healthchecks`	Datenbankname
`DB_USER`	`healthchecks`	Datenbankbenutzer
`DB_PASSWORD`	`${POSTGRES_PASSWORD}`	Datenbankpasswort (aus `.env`)
`DEFAULT_FROM_EMAIL`	`healthchecks@robinwerner.net`	Absender-Adresse fuer E-Mails
`EMAIL_HOST`	`smtp.eu.mailgun.org`	SMTP-Server
`EMAIL_HOST_USER`	`healthchecks@mailgun.robinwerner.net`	SMTP-Benutzername
`EMAIL_HOST_PASSWORD`	`${HEALTHCHECKS_SMTP_PASSWORD}`	SMTP-Passwort (aus `.env`)
`PING_BODY_LIMIT`	`100000`	Max. Groesse des Ping-Bodys (Bytes)
`PING_EMAIL_DOMAIN`	`hc.homelab-external.robinwerner.net`	Domain fuer E-Mail-Pings
`REGISTRATION_OPEN`	`False`	Keine oeffentliche Registrierung
`SECRET_KEY`	`${HEALTHCHECKS_SECRET}`	Django Secret Key (aus `.env`)
`SITE_NAME`	`Homelab Healthchecks`	Anzeigename in der Web-UI
`SITE_ROOT`	`https://hc.homelab-external.robinwerner.net`	Basis-URL

DNS-Konfiguration:

dns:
  - 10.10.10.3   # Pi-hole (primaer)
  - 1.1.1.1      # Cloudflare (Fallback)

PostgreSQL (Healthchecks)¶

Parameter	Wert
Image	`postgres:17.9-alpine`
Netzwerk	`internal` (kein Traefik-Zugriff)
Daten	`/opt/homelab-data/healthchecks-postgres`
Datenbank	`healthchecks` / User `healthchecks`

Das DB-Passwort wird ueber POSTGRES_PASSWORD aus .env gesetzt — derselbe Wert gilt auch fuer die Headscale-Datenbank.

Netzwerk¶

Healthchecks ist sowohl im proxy-Netzwerk (fuer Traefik) als auch im internal-Netzwerk (fuer den Datenbankzugriff).

Traefik-Routing:

hc.homelab-external.robinwerner.net → healthchecks:8000

Middlewares: security-headers (HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy)

Wichtige Konfiguration¶

Ping-URL-Schema¶

Jeder Check bekommt eine eindeutige UUID-URL:

https://hc.homelab-external.robinwerner.net/ping/<uuid>        # Erfolg
https://hc.homelab-external.robinwerner.net/ping/<uuid>/start  # Job gestartet
https://hc.homelab-external.robinwerner.net/ping/<uuid>/fail   # Job fehlgeschlagen
https://hc.homelab-external.robinwerner.net/ping/<uuid>/log    # Log-Daten senden

Cron-Job-Integration (Beispiel)¶

# In crontab:
# Borg-Backup taeglich um 02:00
0 2 * * * /usr/local/bin/borgmatic && curl -fsS -m 10 --retry 5 \
  https://hc.homelab-external.robinwerner.net/ping/<uuid> > /dev/null

Benachrichtigungskanale¶

Healthchecks unterstuetzt via Apprise eine Vielzahl von Kanalen. Empfohlen: ntfy ueber die Apprise-URL: ntfy://user:pass@ntfy.homelab-external.robinwerner.net/homelab-alerts

E-Mail-Pings¶

Mit PING_EMAIL_DOMAIN koennen Checks auch per E-Mail getriggert werden: <uuid>@hc.homelab-external.robinwerner.net

Wartung¶

Ersteinrichtung¶

# Django Superuser anlegen
docker exec healthchecks ./manage.py createsuperuser --noinput --email admin@example.com
# Passwort anschliessend in der Web-UI setzen

Management-Kommandos¶

# Datenbankmigrationen manuell ausfuehren (nach Update)
docker exec healthchecks ./manage.py migrate

# Abgelaufene Ping-Logs bereinigen
docker exec healthchecks ./manage.py pruneflips --weeks=12

# Token-Bucket bereinigen
docker exec healthchecks ./manage.py prunetokenbucket

Logs¶

docker compose logs -f healthchecks
docker compose logs -f healthchecks-postgres

Healthcheck¶

Der interne Healthcheck sendet eine HTTP-Anfrage an /api/v3/status/ mit dem korrekten Host-Header (Django lehnt Anfragen an localhost ab):

curl -H "Host: hc.homelab-external.robinwerner.net" http://localhost:8000/api/v3/status/

Backup¶

Alle persistenten Daten liegen in:

/opt/homelab-data/healthchecks — Anwendungsdaten
/opt/homelab-data/healthchecks-postgres — PostgreSQL-Daten

Update¶

Images sind auf konkrete Versionen gepinnt. Renovate erstellt woechtentlich PRs fuer Updates. Nach Merge auf main wird der Stack automatisch per Cron-Job (dienstags 12:00 UTC) aktualisiert.

# Manuelles Update
cd /opt/homelab-repo/hetzner
docker compose pull healthchecks healthchecks-postgres
docker compose up -d healthchecks healthchecks-postgres

Keine oeffentliche Registrierung

REGISTRATION_OPEN=False verhindert, dass fremde Personen Accounts anlegen. Neue Benutzer muessen per createsuperuser oder Django-Admin angelegt werden.