Send your docker stats and and events to mqtt and discovery them in home assistant.
Project description
docker2mqtt - Deliver docker status information over MQTT
This program uses docker events
to watch for changes in your docker 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.
Running
It available as python package on pypi or as a docker image.
Pypi package
pip install docker2mqtt
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 |
ping |
The MQTT topic prefix. With the default data will be published to ping/<hostname> . |
mqtt_qos |
MQTT_QOS |
1 |
The MQTT QOS level |
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 can be inspected in type_definitions.py or the documentation.
Home Assistant
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, which you can then expose using template sensors if you wish.
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:
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.0
- Rework of the complete structure, but no functional changes.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for docker2mqtt-2.0.0rc1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d24cbcf967c3423ab55afbe6a9d5d37bd5610f3c785dbff85c2ea1fe7edc749a |
|
MD5 | 342271ed5bee47d85861f05578535e17 |
|
BLAKE2b-256 | 0483708140ab995c363f229078b545a7c345f11f634d87db4d4b7801eddf974f |