What is monocker?

Monocker is a lightweight Node.js application that runs as a Docker container and monitors other Docker containers for state changes such as paused, exited, unhealthy, or dead. It can include or exclude specific containers via labels, and optionally only alert on offline states. Notifications are delivered through a wide range of messaging platforms including Telegram, Discord, Slack, Gotify, Matrix, Pushover, Pushbullet, Ntfy, and Apprise. The application exposes a health check endpoint on port 8000 and requires access to the Docker socket. It is configured entirely through environment variables and runs on a configurable polling interval (default 30 seconds).

Should you self-host monocker?

monocker scores 47/100 on selfhost.directory (how scoring works) and ranks #70 of 104 in Monitoring & observability. It has 199 GitHub stars.

There was no stable release in the past 12 months, so check the repository's recent activity before you rely on it.

Setup is easy: most people get it running in one sitting. An official Docker image is available. It is MIT-licensed and written mostly in JavaScript.

Its closest alternative on selfhost.directory is grafana (90/100, 77 568 stars). It scores higher overall, so compare the two before you pick. See monocker vs grafana side by side.

Features

Built-in Docker healthcheck
Configurable poll interval
Container inclusion/exclusion
Container SHA in messages
Container state monitoring
Custom Ntfy server support
Label-based container filtering
Multi-Platform Notifications
Offline-only alerts
Startup message suppression

How to configure monocker

CUSTOM_NTFY_SERVERThe URL for your self-hosted Ntfy server (else uses https://ntfy.sh).
The URL for your self-hosted Ntfy server (else uses https://ntfy.sh).
DISABLE_STARTUP_MSGfalseSuppresses startup messages from being sent.
Suppresses startup messages from being sent.
values: true, false
DOCKER_HOSTUse a docker interface other than the default (e.g., tcp://docker-socket-proxy:2375). Can be a UNIX socket, Windows named pipe, or TCP connection.
Use a docker interface other than the default (e.g., tcp://docker-socket-proxy:2375). Can be a UNIX socket, Windows named pipe, or TCP connection.
values: unix://, npipe://, tcp://
EXCLUDE_EXITEDfalseIgnore or include the status of 'exited' regardless of other settings.
Ignore or include the status of 'exited' regardless of other settings.
values: true, false
LABEL_ENABLEfalseIncludes or excludes specified containers if labelled. Defaults to false.
Includes or excludes specified containers if labelled. Defaults to false.
values: true, false
MESSAGE_PLATFORMSpecify one messaging platform with credentials (required).
Specify one messaging platform with credentials (required).
values: pushbullet@api_key@device_id, pushover@user_key@app_token, discord@webhook_url, ntfy@topic_title, slack@bot_token@chat_id, gotify@server_url@app_token, telegram@bot_id@chat_id, apprise@url@config_id@tag, matrix@server@user@token@room
NTFY_PASSThe password to login to Ntfy server.
The password to login to Ntfy server.
NTFY_USERThe username to login to Ntfy server.
The username to login to Ntfy server.
ONLY_OFFLINE_STATESfalseWhen true, only notify when container state changes to paused, exited, running (unhealthy), or dead. Otherwise, all state changes are notified.
When true, only notify when container state changes to paused, exited, running (unhealthy), or dead. Otherwise, all state changes are notified.
values: true, false
PERIOD10Set the poll period in seconds. Default/minimum is 10 seconds, recommended 30 seconds.
Set the poll period in seconds. Default/minimum is 10 seconds, recommended 30 seconds.
SERVER_AVATARAvatar image URL to add to messages. Supported by Discord, Slack, and Ntfy.
Avatar image URL to add to messages. Supported by Discord, Slack, and Ntfy.
SERVER_LABELLabel to preface messages. Handy if running multiple Monocker instances.
Label to preface messages. Handy if running multiple Monocker instances.
SHAfalseInclude the container SHA ID in sent messages.
Include the container SHA ID in sent messages.
values: true, false