Watchdog verwendet eine zweistufige Monitoring-Architektur:
/proc, Docker-Socket, laufende Prozesse.Jeder Check-Typ deklariert seinen Runner-Modus: DashboardOnly, AgentOnly oder Both.
Vor dem Start eines Agenten-Containers muss ein Agenten-Eintrag im Dashboard angelegt werden:
host-server oder kunde-acme)Jeder überwachte Server erhält einen eigenen Agenten-Eintrag und Token.
Die Watchdog-Compose-Dateien (compose.yml, compose.stage.yml) enthalten bereits einen agent-Service. Er verwendet dasselbe Docker-Image wie die App, führt aber den Agenten-Prozess aus — kein separater Image-Pull nötig.
WATCHDOG_AGENT_TOKEN in der Umgebungsdatei eintragen:
# .env.stage oder .env.local
WATCHDOG_AGENT_TOKEN=dein-token-hier
# Stage
docker compose -f compose.stage.yml up -d agent
# Dev
docker compose up -d agent
Der Agent verbindet sich via internem Docker-Netzwerk mit dem app-Container (http://app:80) — keine externe URL nötig.
Der Docker-Socket ist standardmäßig auskommentiert. Um Docker Container Health und Docker Exec zu aktivieren, in der Compose-Datei einkommentieren:
# compose.stage.yml
agent:
volumes:
- /:/host/root:ro
- /var/run/docker.sock:/var/run/docker.sock:ro # diese Zeile einkommentieren
agent:
# Verwendet dasselbe Image wie die App
image: watchdog-stage
environment:
WATCHDOG_DASHBOARD_URL: http://app:80 # Internes Docker-Netzwerk
WATCHDOG_AGENT_TOKEN: dein-token # Aus Einstellungen > Agenten
HOST_ROOT: /host/root # Mappt Pfade auf das gemountete Host-FS
TZ: Europe/Berlin
pid: host # Pflicht fĂĽr ProcessCheck
volumes:
- /:/host/root:ro # Pflicht fĂĽr Festplatten-/Datei-Checks
# - /var/run/docker.sock:/var/run/docker.sock:ro # Docker-Checks
restart: unless-stopped
Um einen separaten Server (z.B. einen Kundenserver) zu ĂĽberwachen, den Standalone-Agenten dort deployen:
docker pull ghcr.io/markus-michalski/watchdog/agent:latest
Die docker-compose.agent.yml aus dem Repository als Vorlage verwenden:
# docker-compose.agent.yml
services:
watchdog-agent:
image: ghcr.io/markus-michalski/watchdog/agent:latest
restart: unless-stopped
environment:
WATCHDOG_DASHBOARD_URL: https://watchdog.yourdomain.com
WATCHDOG_AGENT_TOKEN: dein-agenten-token
HOST_ROOT: /host/root
TZ: Europe/Berlin
pid: host # Pflicht fĂĽr ProcessCheck
volumes:
- /:/host/root:ro # Pflicht fĂĽr Festplatten-/Datei-Checks
# - /var/run/docker.sock:/var/run/docker.sock:ro
Auf dem Remote-Server einrichten:
curl -O https://raw.githubusercontent.com/markus-michalski/watchdog/main/docker-compose.agent.yml
# WATCHDOG_DASHBOARD_URL und WATCHDOG_AGENT_TOKEN anpassen
docker compose -f docker-compose.agent.yml up -d
Der Remote-Server muss die Watchdog-Dashboard-URL über HTTPS (oder HTTP im privaten Netz) erreichen können.
| Variable | Pflicht | Beschreibung |
|---|---|---|
WATCHDOG_DASHBOARD_URL |
Ja | Basis-URL des Watchdog-Dashboards, ohne abschlieĂźenden Slash. http://app:80 fĂĽr Host-Agenten via Docker-Netzwerk, https://watchdog.yourdomain.com fĂĽr Remote-Agenten. |
WATCHDOG_AGENT_TOKEN |
Ja | Bearer-Token aus dem Dashboard unter Einstellungen → Agenten. |
HOST_ROOT |
Für Datei-/Festplatten-Checks | Pfad-Präfix, der den konfigurierten Dateipfaden vorangestellt wird. Auf /host/root setzen, wenn das Host-Dateisystem dort gemountet ist. |
TZ |
Empfohlen | Zeitzone fĂĽr Log-Timestamps (z.B. Europe/Berlin). |
| Check-Typ | Benötigt |
|---|---|
| Festplatte, Datei-Alter, Dateigröße, Log-Datei | - /:/host/root:ro + HOST_ROOT=/host/root |
| Prozess | pid: host |
| Docker Container Health, Docker Exec | - /var/run/docker.sock:/var/run/docker.sock:ro |
| HTTP, SSL, TCP, DNS, Redis, Datenbank (Both-Modus) | Keine speziellen Mounts |
/api/v1/agent/config.run_now-Flags (ausgelöst über "Jetzt ausführen" in der UI) und führt fällige Checks gemäß ihrem konfigurierten Intervall aus./api/v1/agent/results gepusht.Signalbehandlung: Der Agent fährt bei SIGTERM und SIGINT sauber herunter.
Agent erscheint als offline im Dashboard
docker logs watchdog-stage-agent
Häufige Ursachen:
WATCHDOG_AGENT_TOKEN nicht gesetzt oder falschWATCHDOG_DASHBOARD_URL vom Agenten-Container nicht erreichbarFestplatten-/Datei-Checks liefern "Pfad nicht gefunden"
Die Umgebungsvariable HOST_ROOT ist nicht gesetzt oder das Host-Dateisystem ist nicht gemountet. PrĂĽfen:
- /:/host/root:ro ist in der Volumes-Liste vorhandenHOST_ROOT: /host/root ist in der Environment-Sektion gesetztProcessCheck liefert immer Fail
Die Option pid: host fehlt in der Agent-Service-Definition. Ohne sie sieht der Agent nur Prozesse im eigenen Container.