¶ Watchdog
¶ Navigation
- Agenten einrichten — Host-Agent, Remote-Agenten, Tokens, Volumes
- Check-Typen — Alle 14 eingebauten Check-Typen mit Konfigurationsreferenz
- Eigene Checks schreiben — Eigenen Check-Typ in PHP implementieren
- GitHub
Watchdog ist eine selbst gehostete Monitoring-Anwendung für Websites, Container und Server-Infrastruktur. Sie läuft als Docker-first-Anwendung ohne externe Datenbankabhängigkeiten — SQLite übernimmt die gesamte Datenpersistenz lokal.
Das Monitoring läuft in zwei Modi: Dashboard-Checks werden vom Watchdog-Server selbst ausgeführt (HTTP-Erreichbarkeit, SSL-Zertifikate), während Agenten-Checks auf dem überwachten Server via einem leichtgewichtigen Docker-Container laufen und die Ergebnisse an das Dashboard zurückschicken.
Lizenz: PolyForm Noncommercial License 1.0.0 — Source-Available, kostenlos für persönliche und nicht-kommerzielle Nutzung. Kein OSI-Open-Source. Kommerzielle Nutzung erfordert eine explizite Genehmigung.
¶ Funktionen
| Funktion | Details |
|---|---|
| Check-Typen | 14 eingebaute Typen: HTTP, HTTP-Inhalt, SSL, DNS, TCP, Docker, Docker Exec, Festplatte, Load Average, Prozesse, Log-Datei, Datei-Alter, Dateigröße, Redis, Datenbank |
| Agenten-Monitoring | Leichtgewichtiger Docker-Agent für Remote-/Kundenserver — holt Checks vom Dashboard, schickt Ergebnisse zurück |
| Alert-Logik | E-Mail-Benachrichtigungen nur bei Statuswechseln (ok→fail, fail→ok) — kein Spam |
| Keine externen Abhängigkeiten | SQLite-Datenbank, FrankenPHP-All-in-One-Binary — kein MySQL, kein Redis, kein separater Webserver |
| Async-AusfĂĽhrung | Symfony Messenger fĂĽr nicht-blockierende Check-AusfĂĽhrung und E-Mail-Versand |
| Scheduler | Symfony Scheduler fĂĽr intervallbasierte und zeitbasierte Check-AusfĂĽhrung |
¶ Architektur
| Container | Aufgabe |
|---|---|
app |
FrankenPHP-Webserver — UI und REST-API |
worker |
Messenger-Consumer — führt Dashboard-Checks aus, versendet Alert-E-Mails |
scheduler |
Startet fällige Checks gemäß Konfiguration |
agent |
FĂĽhrt Agenten-Checks lokal aus und schickt Ergebnisse an das Dashboard |
mailpit |
Lokaler Mail-Catcher (nur Dev/Stage) |
¶ Installation
¶ 1. Klonen und konfigurieren
git clone https://github.com/markus-michalski/watchdog.git /opt/watchdog
cd /opt/watchdog
cp .env.example .env.local
.env.local bearbeiten:
APP_SECRET=<zufälliger 32-Zeichen-String>
APP_ADMIN_USER=admin
APP_ADMIN_PASSWORD_HASH= # siehe unten
MAILER_DSN=smtp://user:pass@smtp.example.com:587
MAILER_FROM=watchdog@yourdomain.com
DEFAULT_URI=https://watchdog.yourdomain.com
¶ 2. Passwort-Hash generieren
docker run --rm dunglas/frankenphp:1-php8.4-alpine php -r \
"echo password_hash('yourpassword', PASSWORD_BCRYPT) . PHP_EOL;"
Bcrypt-Hashes enthalten $-Zeichen. Jedes $ muss in .env.local zu $$ verdoppelt werden, da Docker Compose $ in Env-Dateien interpoliert:
# Falsch — Docker Compose zerstört den Hash
APP_ADMIN_PASSWORD_HASH=$2y$13$abc...
# Richtig
APP_ADMIN_PASSWORD_HASH=$$2y$$13$$abc...
¶ 3. Bauen und starten
make stage-build
make stage-up
¶ 4. Host-Agenten aktivieren
Im Dashboard unter Einstellungen → Agenten einen neuen Agenten anlegen, Token kopieren und in WATCHDOG_AGENT_TOKEN in .env.local eintragen. Dann den Agent-Container starten:
docker compose -f compose.stage.yml up -d agent
Mehr Details: Agenten einrichten.
¶ Alert-Logik
Benachrichtigungen werden nur bei Statuswechseln per E-Mail versandt:
ok → faillöst eine Fehler-Benachrichtigung ausfail → oklöst eine Wiederherstellungs-Benachrichtigung aus- Wiederholte Fehler ohne Statusänderung erzeugen keine weiteren E-Mails
Empfänger pro überwachter Site konfigurieren: in der UI unter den Kontakteinstellungen des jeweiligen Clients.
¶ Make-Befehle
make stage-up Container starten + Migrationen ausfĂĽhren
make stage-down Container stoppen
make stage-build Image ohne Cache neu bauen
make stage-logs Alle Container-Logs verfolgen
make live-update Zero-Downtime-Rebuild + Redeploy (live)
make test PHPUnit
make stan PHPStan Level 8
Vollständige Liste: make help.
¶ Lizenz & Beitragen
Watchdog steht unter der PolyForm Noncommercial License 1.0.0. Kommerzielle Nutzung erfordert eine separate Vereinbarung.
Beiträge erfordern die Unterzeichnung des Contributor License Agreement. Siehe CONTRIBUTING.md für den Entwicklungs-Workflow.
Bugs und Feature-Requests: GitHub Issues