Description:
docker2mqtt 2.0.3
docker2mqtt - Deliver docker status information over MQTT
This program uses docker events to watch for changes in your docker containers, and docker stats for metrics about those containers, and delivers current status to MQTT. It will also publish Home Assistant MQTT Discovery messages so that (binary) sensors automatically show up in Home Assistant.
This is part of a family of similar tools:
miaucl/linux2mqtt
miaucl/docker2mqtt
miaucl/systemctl2mqtt
Installation and Deployment
It is available as python package on pypi/docker2mqtt or as a docker image on ghcr.io/docker2mqtt.
Pypi package
pip install docker2mqtt
docker2mqtt --name MyDockerName --events -vvvvv
Usage
from docker2mqtt import Docker2Mqtt, DEFAULT_CONFIG
cfg = Docker2MqttConfig({
**DEFAULT_CONFIG,
"host": "mosquitto",
"enable_events": True
})
try:
docker2mqtt = Docker2Mqtt(cfg)
docker2mqtt.loop_busy()
except Exception as ex:
# Do something
Docker image
Use docker to launch this. Please note that you must give it access to your docker socket, which is typically located at /var/run/docker.sock. A typical invocation is:
docker run --network mqtt -e MQTT_HOST=mosquitto -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/miaucl/docker2mqtt
You can also use docker compose:
services:
docker2mqtt:
container_name: docker2mqtt
image: ghcr.io/miaucl/docker2mqtt
environment:
- DOCKER2MQTT_HOSTNAME=my_docker_host
- MQTT_HOST=mosquitto
- MQTT_USER=username
- MQTT_PASSWD=password
- EVENTS=1
- STATS=1
restart: unless-stopped
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
Default Configuration
You can use environment variables to control the behavior.
Config
Env Variable
Default
Description
log_level
LOG_LEVEL
INFO
Set to DEBUG,INFO,WARN,ERROR,CRITICAL to enable different levels of verbosity.
docker2mqtt_hostname
DOCKER2MQTT_HOSTNAME
docker2mqtt Container Hostname
The hostname of your docker host. This will be the container's hostname by default, you probably want to override it.
homeassistant_prefix
HOMEASSISTANT_PREFIX
homeassistant
The prefix for Home Assistant discovery. Must be the same as discovery_prefix in your Home Assistant configuration.
mqtt_client_id
MQTT_CLIENT_ID
mqtt2discord
The client id to send to the MQTT broker.
mqtt_host
MQTT_HOST
localhost
The MQTT broker to connect to.
mqtt_port
MQTT_PORT
1883
The port on the broker to connect to.
mqtt_user
MQTT_USER
The user to send to the MQTT broker. Leave unset to disable authentication.
mqtt_password
MQTT_PASSWD
The password to send to the MQTT broker. Leave unset to disable authentication.
mqtt_timeout
MQTT_TIMEOUT
30
The timeout for the MQTT connection.
mqtt_topic_prefix
MQTT_TOPIC_PREFIX
docker
The MQTT topic prefix. With the default data will be published to docker/<hostname>.
mqtt_qos
MQTT_QOS
1
The MQTT QOS level
container_whitelist
CONTAINER_WHITELIST
Define a whitelist for containers to consider, if empty, everything is monitored. The entries are either match as literal strings or as regex.
container_blacklist
CONTAINER_BLACKLIST
Define a blacklist for containers to consider, takes priority over whitelist. The entries are either match as literal strings or as regex.
destroyed_container_ttl
DESTROYED_CONTAINER_TTL
86400
How long, in seconds, before destroyed containers are removed from Home Assistant. Containers won't be removed if the service is restarted before the TTL expires.
stats_record_seconds
STATS_RECORD_SECONDS
30
The number of seconds to record state and make an average
enable_events
EVENTS
0
1 Or 0 for processing events
enable_stats
STATS
0
1 Or 0 for processing statistics
Consuming The Data
Data is published to the topic docker/<DOCKER2MQTT_HOSTNAME>/<container>/events using JSON serialization. It will arrive whenever a change happens and its type can be inspected in type_definitions.py or the documentation.
Data is also published to the topic docker/<DOCKER2MQTT_HOSTNAME>/<container>/stats using JSON serialization. It will arrive every STATS_RECORD_SECONDS seconds or so and its type can be inspected in type_definitions.py or the documentation.
Home Assistant
Once docker2mqtt is collecting data and publishing it to MQTT, it's rather trivial to use the data in Home Assistant.
A few assumptions:
Home Assistant is already configured to use a MQTT broker. Setting up MQTT and HA is beyond the scope of this documentation. However, there are a lot of great tutorials on YouTube. An external broker (or as add-on) like Mosquitto will need to be installed and the HA MQTT integration configured.
The HA MQTT integration is configured to use homeassistant as the MQTT autodiscovery prefix. This is the default for the integration and also the default for docker2mqtt. If you have changed this from the default, use the --prefix parameter to specify the correct one.
You're not using TLS to connect to the MQTT broker. Currently docker2mqtt only works with unencrypted connections. Username / password authentication can be specified with the --username and --password parameters, but TLS encryption is not yet supported.
After you start the service (binary) sensors should show up in Home Assistant immediately. Look for sensors that start with (binary_)sensor.docker. Metadata about the container will be available as attributes for events, which you can then expose using template sensors if you wish.
Documentation
Using mkdocs, the documentation and reference is generated and available on github pages.
Dev
Setup the dev environment using VSCode, it is highly recommended.
python -m venv .venv
source .venv/bin/activate
pip install -r requirements_dev.txt
Install pre-commit
pre-commit install
# Run the commit hooks manually
pre-commit run --all-files
Following VSCode integrations may be helpful:
ruff
mypy
markdownlint
Credits
This is a detached fork from the repo https://github.com/skullydazed/docker2mqtt, which does not seem to get evolved anymore.
CHANGELOG
2.0.5
Re-release due to bad deploy pipeline
2.0.4
Update the discovery jsons for home assistant
2.0.3
Transform the mqtt port cli arg to int as a str is not accepted by the paho.mqtt library
Fix the container filter not only at startup but also at runtime
2.0.2
Add version cli options to display package version
Separate the entrypoints for cli (using cli arguments) and docker (using env vars)
2.0.1
Fix white- and blacklist config via docker env where and empty string resulted in a pass-all regex overwriting the blacklist.
2.0.0
Rework of the complete structure, but no functional changes.
License
For personal and professional use. You cannot resell or redistribute these repositories in their original state.
Customer Reviews
There are no reviews.
