¶ Watchdog
This documentation always describes the latest published version.
Watchdog is a self-hosted monitoring application for websites, containers and servers. It runs as a Docker Compose stack and stores everything in a single SQLite file, so no database server is needed.
Monitoring works in two modes: the Watchdog server runs dashboard checks itself, such as HTTP, SSL, TCP or DNS. Agent checks run in a small container on the monitored machine and report their results back, such as disk, processes or files.
Live demo: Try Watchdog live at demo.markus-michalski.net, no installation and no risk.
¶ Overview
¶ Documentation
| Page | Content |
|---|---|
| Installation | Docker Compose stack for local, stage and live, update, backup, uninstall |
| Configuration | Environment variables, clients, contacts, URLs and check settings |
| Usage and Commands | Dashboard, Run now, history, make and console commands |
| Check Types | All 15 check types with fields, statuses and messages |
| Notifications | When and how Watchdog sends emails |
| Agents | Set up host and remote agents |
| Writing Custom Checks | Add your own check type in PHP |
| Security and Privacy | Access, tokens, privileges, stored data |
| Technical Details | Architecture, flow, data model, agent API |
| Troubleshooting | Symptoms, checks and solutions |
¶ Features
| Feature | Details |
|---|---|
| Check types | 15 built-in types: HTTP, HTTP Content, SSL Certificate, DNS, TCP Port, Redis, Database, Docker, Docker Exec, Disk Space, Load Average, Process, Log File, File Age, File Size |
| Agents | Agent container for host and remote servers that pulls checks and pushes results |
| Scheduling | Interval in days, hours and minutes or once a day at a time of day, Run now for immediate runs |
| Alerts | Email to a client's contacts on a change to WARN or FAIL and on recovery, no repeated emails |
| History | Results per check with filters, configurable retention in days |
| Extensible | Custom check types as a PHP class |
| No database server | SQLite, Messenger queue in the same database |
¶ Requirements
| Component | Requirement |
|---|---|
| Docker with the Compose plugin | All services run as containers |
| PHP and Symfony | PHP 8.4 and Symfony 8.1, contained in the image |
| Mail server | SMTP access for alert emails (Mailpit catches them locally and on stage) |
| Reverse proxy with HTTPS | For stage and live, the app listens on 127.0.0.1 only |
¶ License
Watchdog is licensed under the PolyForm Noncommercial License 1.0.0. The source is available and use is free for personal and non-commercial purposes. It is not an OSI open-source license. Commercial use requires explicit permission from the maintainer.
Contributions require the Contributor License Agreement. The development workflow is described in CONTRIBUTING.md.
¶ Support
Bugs and feature requests: GitHub Issues. Report security vulnerabilities through the repository's private vulnerability reporting, see Security and Privacy.