darkmatterforge/chowkidar repository overview

⁠Chowkidar

Chowkidar watches your containers for unhealthy health events and exited states, then reacts automatically — restarting, stopping, or running a custom script — and sends notifications via Discord, Slack, Telegram, email, and more.

⁠Features

• Container monitoring — polls Docker for unhealthy and exited containers; supports Docker-native health checks and custom bash health-check scripts per job
• Configurable actions — restart, start, stop, none, run-script per job
• Per-job health-check script — define a bash script that determines container health (exit 0 = healthy, non-zero = unhealthy); dry-run and template picker included
• Per-job overrides — individual retry count, monitoring interval, action timeout, and post-action wait
• Multi-context job rules — pin each job to one or more Docker contexts; jobs with no context run on all hosts
• Multi-provider notifications — Discord, Slack, Telegram, ntfy, Gotify, Pushover, SMTP/email, raw Apprise URLs
• Notification templates — customise message content per provider per lifecycle event
• Jobs system — define targeted monitoring rules with container name/label/env var filters
• Bash script action — run a custom inline script per job with built-in templates, dry-run execution, and automatic template upgrade detection
• Multi-Docker-host — monitor containers across multiple Docker hosts or sockets; each host individually enabled/disabled with its own monitoring interval, ping timeout, and offline confirm window
• Per-host offline notifications — configure notification agents and custom message templates per Docker host; notifies once on down, once on recovery (no spam)
• Web UI — dashboard, jobs, notification profiles, action history, settings
• Authentication — optional username/password protection with bcrypt hashing
• Encryption — notification credentials encrypted at rest via CHOWKIDAR_SECRET_KEY
• 3 dashboard layouts — Card List, Compact Table, Status Grid; service groups are collapsible with state persisted across reloads
• Dashboard filters — filter by status, tag, job action, Docker host, container name, label, env var, and job name; advanced filters panel for power users
• Maintenance windows — schedule service pauses using six strategies (Manual, Single Window, Cron, Interval, Day of Week, Day of Month); targets jobs or Docker hosts (mutually exclusive); optional effective date ranges; per-window control over queued/in-flight action handling when a window opens (allow-finish / cancel-queued / force-cancel); bell notifications on start and end; auto-prune of expired single-occurrence windows
• Notification bell — persistent system alerts (boot, failed recovery, paused monitoring) with per-alert dismiss and mark-all-read
• Version check — settings sidebar shows running version; background check surfaces a bell alert when a newer release is available
• Light/dark/auto theme
• Persistent config — everything stored under /config (YAML + JSON history + logs)
• Docker socket proxy support for reduced attack surface

⁠Quick Start

docker compose up -d

Open http://localhost:8080

⁠Development

Runs with live reload via Air⁠. Go file changes rebuild the binary automatically; web/ is served directly from disk so HTML/CSS/JS changes are visible on refresh with no rebuild.

docker compose -f docker-compose.dev.yml up --build

Open http://localhost:8080

⁠Docker CLI

docker run -d \
  --name chowkidar \
  --restart unless-stopped \
  -p 8080:8080 \
  -e CHOWKIDAR_SECRET_KEY=your-long-random-secret \
  -v /mnt/user/appdata/chowkidar:/config \
  -v /var/run/docker.sock:/var/run/docker.sock \
  darkmatterforge/chowkidar:latest

⁠Environment Variables

Most settings are configured through the web UI (Settings page) and persisted to /config/config.yaml. The env vars below are the ones you typically set at container creation time. Every env var still overrides the config file if set.

⁠Required at startup

⁠Docker connectivity

Chowkidar connects to Docker via the mounted socket by default. Additional Docker hosts are added through Settings → Docker Hosts in the web UI. Each host can be individually enabled/disabled and has its own monitor interval, ping timeout, and offline notification settings.

⁠Container filtering

Useful to set at the container level so monitoring starts correctly on first boot:

⁠Logging

⁠Advanced overrides

All of these are also configurable via the web UI. Set as env vars only if you need to enforce values that the UI cannot override (e.g. in a managed deployment).

⁠Notification Providers

Configure via the web UI under Settings → Notifications.

⁠Notification Events

Templates can be customised per provider for each lifecycle event:

Template variables: {{.ContainerName}}, {{.Action}}, {{.Reason}}, {{.Cycle}}, {{.MaxRetries}}, {{.Cooldown}}, {{.RuleName}}

⁠API

⁠Unraid

Install via Community Applications or add the template manually:

https://raw.githubusercontent.com/darkmatterforge/chowkidar/main/unraid/chowkidar.xml

Map /mnt/user/appdata/chowkidar → /config and set CHOWKIDAR_SECRET_KEY.

⁠License

AGPL-3.0⁠ — Copyright (C) 2026 Dark Matter Forge.

You may use and build on this software, but any modified version must remain open source under the same terms. See NOTICE⁠ for full usage terms and trademark information.