Rethinking the World

Every now and then you hit a point where you want something simple, local, and reliable, and not another “cloud observability platform” that requires half a DevOps pipeline just to know when your proxy throws a 500. And that’s exactly how my Caddy Monitor Service project was born.

I’ve been using Caddy as a reverse proxy for a few internal projects and micro-apps, mostly because it’s fast, flexible, and easy to configure. But I wanted a small companion process that could watch its logs, detect errors, and send an email when something broke. No Grafana dashboards, no external agents, just a self-contained Python service.

What It Does

Caddy Monitor Service is a tiny Windows background service that watches your Caddy JSON logs and sends email alerts whenever an error pops up. Yes, Windows. The other platforms have all the built ins and easy tools – Windows can be a heft at times to serve and monitor on in a lightweight, efficient manner.

It’s built for small internal environments, think a few self-hosted services running behind Caddy on a Windows machine or server, and is designed to just work out of the box.

Here’s the core of what it does:

• Real-time Log Monitoring – continuously tails your caddy_access.log
• Email Alerts – configurable notifications for errors (400–504 by default)
• Customizable Config – tweak your intervals, error codes, SMTP creds, and paths
• SSL Helper Tools – batch scripts to spin up self-signed certs if you need them
• Windows-Friendly Setup – install with a single setup.bat and it just runs

The idea was to keep it simple enough to throw on a VM or workstation and forget about it, until it needs to remind you something went wrong.

Under the Hood

The project is organized cleanly, using a classic Python service pattern:

caddy-monitor-service/
├── monitor/
│   ├── log_checker.py      # Scans and filters logs
│   └── utils.py            # Email + helper utilities
├── config/
│   ├── config.example.ini  # Configuration template
│   └── Caddyfile.example   # Sample Caddy setup
├── scripts/
│   ├── run_monitor.bat     # Launches the monitor
│   └── generate_certs.bat  # Creates self-signed certs
└── tests/
    ├── test_log_checker.py
    └── test_utils.py

The real action happens in monitor/log_checker.py.
It parses Caddy’s JSON-formatted access logs, filters out harmless requests (like uptime checkers or LogicMonitor pings), and looks for the error codes. When it finds them, it triggers a short-cooldown email alert using utils.py’s SMTP logic.

Smart Filtering, Minimal Noise

One of the main goals was to reduce false alarms. A log watcher that cries wolf every five minutes is worse than no alerts at all!

The script ignores status codes like 200, 201, and 304, and can also skip lines containing common monitoring agents (unless you want to!). You can edit the config file to watch only the codes you want, maybe just 500, or all client errors.

You also get built-in rate limiting: it won’t spam you with the same alert over and over within the check interval.

Testing It Properly

This release ships with a proper test suite. You can run:

python -m pytest tests/ -v

or for coverage:

python -m pytest tests/ --cov=monitor --cov-report=html

Everything is self-contained — no external dependencies beyond Python 3.10+, so it runs fine on local machines or Windows Server instances.

Getting Started

Once you clone the repo, just run:

setup.bat

That script:

• creates a Python virtual environment
• installs dependencies
• generates your config and log folders
• sets everything up for your first run

After that, you can launch it manually or set it up in Task Scheduler to run every 15 minutes as a pseudo-service. You can even run Caddy itself as a scheduled service the same way. The README walks you through all the PowerShell and OpenSSL certificate steps.

A Note on Security

The service is designed for internal use or firewalled environments, not the fully open internet.
Store your SMTP credentials safely, protect your certificate directories, and if possible, use environment variables or a dedicated internal relay for sending alerts.

Why This Exists

This project came out of my own need to monitor Caddy-based internal apps without adding overhead. There’s something satisfying about building a single-purpose tool that’s transparent, editable, and does its job well.

It’s also a great little pattern for other self-hosted setups. Swap Caddy for Nginx or Apache, adjust the regexes, and you’ve got a lightweight alerting agent for just about anything.

What’s Next

Future ideas floating around:

• Adding Slack or Teams webhook notifications
• Making it a true Windows service via pywin32
• Packaging it with a small web UI dashboard
• Adding JSON schema validation for logs

Grab It

You can check out the code here:
👉 github.com/macroflux/caddy-monitor-service

MIT licensed, open source, and built with ❤️ for anyone tired of babysitting log files.