# docker2mqtt - Deliver docker status information over MQTT
[](https://github.com/miaucl/docker2mqtt/actions/workflows/mypy.yaml)
[](https://github.com/miaucl/docker2mqtt/actions/workflows/ruff.yml)
[](https://github.com/miaucl/docker2mqtt/actions/workflows/markdownlint.yml)
[](https://github.com/miaucl/docker2mqtt/actions/workflows/publish.yml)
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](https://github.com/miaucl/linux2mqtt)
* [miaucl/docker2mqtt](https://github.com/miaucl/docker2mqtt)
* [miaucl/systemctl2mqtt](https://github.com/miaucl/systemctl2mqtt)
## Installation and Deployment
It is available as python package on [pypi/docker2mqtt](https://pypi.org/p/docker2mqtt) or as a docker image on [ghcr.io/docker2mqtt](https://github.com/miaucl/docker2mqtt/pkgs/container/docker2mqtt).
### Pypi package
[](https://pypi.org/p/docker2mqtt)
```bash
pip install docker2mqtt
docker2mqtt --name MyDockerName --events -vvvvv
```
Usage
```python
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
[![1] ![2] ![3]](https://github.com/miaucl/docker2mqtt/pkgs/container/docker2mqtt)
[1]: <https://ghcr-badge.egpl.dev/miaucl/docker2mqtt/tags?color=%23B8860B&ignore=latest&n=1&label=image&trim=>
[2]: <https://ghcr-badge.egpl.dev/miaucl/docker2mqtt/tags?color=%2344cc11&ignore=latest,*-rc*&n=3&label=image&trim=>
[3]: <https://ghcr-badge.egpl.dev/miaucl/docker2mqtt/size?color=%231E90FF&tag=latest&label=image+size&trim=>
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:
```yaml
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](https://github.com/miaucl/docker2mqtt/blob/master/docker2mqtt/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](https://github.com/miaucl/docker2mqtt/blob/master/docker2mqtt/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](https://mosquitto.org/) 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](https://miaucl.github.io/docker2mqtt/).
## Dev
Setup the dev environment using VSCode, it is highly recommended.
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements_dev.txt
```
Install [pre-commit](https://pre-commit.com)
```bash
pre-commit install
# Run the commit hooks manually
pre-commit run --all-files
```
Following VSCode integrations may be helpful:
* [ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff)
* [mypy](https://marketplace.visualstudio.com/items?itemName=matangover.mypy)
* [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)
### Releasing
It is only possible to release a _final version_ on the `master` branch. For it to pass the gates of the `publish` workflow, it must have the same version in the `tag`, the `setup.cfg`, the `bring_api/__init__.py` and an entry in the `CHANGELOG.md` file.
To release a prerelease version, no changelog entry is required, but it can only happen on a feature branch (**not** `master` branch). Also, prerelease versions are marked as such in the github release page.
## Credits
This is a detached fork from the repo <https://github.com/skullydazed/docker2mqtt>, which does not seem to get evolved anymore.
# CHANGELOG
## 2.1.0
* Update version package identifier and bump setuptools
* Fix mypy setup
## 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/miaucl/docker2mqtt",
"name": "docker2mqtt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "mqtt, paho, docker, metrics",
"author": "Cyrill Raccaud",
"author_email": "cyrill.raccaud+pypi@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e5/59/aaefa5787670d3833823f0edb317c54847aa695a95efc55dd5c41241a960/docker2mqtt-2.1.0.tar.gz",
"platform": null,
"description": "# docker2mqtt - Deliver docker status information over MQTT\n\n[](https://github.com/miaucl/docker2mqtt/actions/workflows/mypy.yaml)\n[](https://github.com/miaucl/docker2mqtt/actions/workflows/ruff.yml)\n[](https://github.com/miaucl/docker2mqtt/actions/workflows/markdownlint.yml)\n[](https://github.com/miaucl/docker2mqtt/actions/workflows/publish.yml)\n\nThis 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.\n\n_This is part of a family of similar tools:_\n\n* [miaucl/linux2mqtt](https://github.com/miaucl/linux2mqtt)\n* [miaucl/docker2mqtt](https://github.com/miaucl/docker2mqtt)\n* [miaucl/systemctl2mqtt](https://github.com/miaucl/systemctl2mqtt)\n\n## Installation and Deployment\n\nIt is available as python package on [pypi/docker2mqtt](https://pypi.org/p/docker2mqtt) or as a docker image on [ghcr.io/docker2mqtt](https://github.com/miaucl/docker2mqtt/pkgs/container/docker2mqtt).\n\n### Pypi package\n\n[](https://pypi.org/p/docker2mqtt)\n\n```bash\npip install docker2mqtt\ndocker2mqtt --name MyDockerName --events -vvvvv\n```\n\nUsage\n\n```python\nfrom docker2mqtt import Docker2Mqtt, DEFAULT_CONFIG\n\ncfg = Docker2MqttConfig({ \n **DEFAULT_CONFIG,\n \"host\": \"mosquitto\",\n \"enable_events\": True\n})\n\ntry:\n docker2mqtt = Docker2Mqtt(cfg)\n docker2mqtt.loop_busy()\n\nexcept Exception as ex:\n # Do something\n```\n\n### Docker image\n\n[![1] ![2] ![3]](https://github.com/miaucl/docker2mqtt/pkgs/container/docker2mqtt)\n\n[1]: <https://ghcr-badge.egpl.dev/miaucl/docker2mqtt/tags?color=%23B8860B&ignore=latest&n=1&label=image&trim=>\n[2]: <https://ghcr-badge.egpl.dev/miaucl/docker2mqtt/tags?color=%2344cc11&ignore=latest,*-rc*&n=3&label=image&trim=>\n[3]: <https://ghcr-badge.egpl.dev/miaucl/docker2mqtt/size?color=%231E90FF&tag=latest&label=image+size&trim=>\n\nUse 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:\n\n`docker run --network mqtt -e MQTT_HOST=mosquitto -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/miaucl/docker2mqtt`\n\nYou can also use docker compose:\n\n```yaml\nservices:\n docker2mqtt:\n container_name: docker2mqtt\n image: ghcr.io/miaucl/docker2mqtt\n environment:\n - DOCKER2MQTT_HOSTNAME=my_docker_host\n - MQTT_HOST=mosquitto\n - MQTT_USER=username\n - MQTT_PASSWD=password\n - EVENTS=1\n - STATS=1\n restart: unless-stopped\n volumes:\n - /var/run/docker.sock:/var/run/docker.sock:ro\n```\n\n## Default Configuration\n\nYou can use environment variables to control the behavior.\n\n| Config | Env Variable | Default | Description |\n|--------|--------------|---------|-------------|\n| `log_level`| `LOG_LEVEL` | `INFO` | Set to `DEBUG,INFO,WARN,ERROR,CRITICAL` to enable different levels of verbosity. |\n| `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. |\n| `homeassistant_prefix`| `HOMEASSISTANT_PREFIX` | `homeassistant` | The prefix for Home Assistant discovery. Must be the same as `discovery_prefix` in your Home Assistant configuration. |\n| `mqtt_client_id`| `MQTT_CLIENT_ID` | `mqtt2discord` | The client id to send to the MQTT broker. |\n| `mqtt_host`| `MQTT_HOST` | `localhost` | The MQTT broker to connect to. |\n| `mqtt_port`| `MQTT_PORT` | `1883` | The port on the broker to connect to. |\n| `mqtt_user`| `MQTT_USER` | | The user to send to the MQTT broker. Leave unset to disable authentication. |\n| `mqtt_password`| `MQTT_PASSWD` | | The password to send to the MQTT broker. Leave unset to disable authentication. |\n| `mqtt_timeout`| `MQTT_TIMEOUT` | `30` | The timeout for the MQTT connection. |\n| `mqtt_topic_prefix`| `MQTT_TOPIC_PREFIX` | `docker` | The MQTT topic prefix. With the default data will be published to `docker/<hostname>`. |\n| `mqtt_qos`| `MQTT_QOS` | `1` | The MQTT QOS level |\n| `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. |\n| `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. |\n| `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. |\n| `stats_record_seconds`| `STATS_RECORD_SECONDS` | `30` | The number of seconds to record state and make an average |\n| `enable_events`| `EVENTS` | `0` | 1 Or 0 for processing events |\n| `enable_stats`| `STATS` | `0` | 1 Or 0 for processing statistics |\n\n## Consuming The Data\n\nData 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](https://github.com/miaucl/docker2mqtt/blob/master/docker2mqtt/type_definitions.py) or the documentation.\n\nData 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](https://github.com/miaucl/docker2mqtt/blob/master/docker2mqtt/type_definitions.py) or the documentation.\n\n## Home Assistant\n\nOnce `docker2mqtt` is collecting data and publishing it to MQTT, it's rather trivial to use the data in Home Assistant.\n\nA few assumptions:\n\n* **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](https://mosquitto.org/) will need to be installed and the HA MQTT integration configured.\n* **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.\n* **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.\n\nAfter 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.\n\n\n\n## Documentation\n\nUsing `mkdocs`, the documentation and reference is generated and available on [github pages](https://miaucl.github.io/docker2mqtt/).\n\n## Dev\n\nSetup the dev environment using VSCode, it is highly recommended.\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements_dev.txt\n```\n\nInstall [pre-commit](https://pre-commit.com)\n\n```bash\npre-commit install\n\n# Run the commit hooks manually\npre-commit run --all-files\n```\n\nFollowing VSCode integrations may be helpful:\n\n* [ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff)\n* [mypy](https://marketplace.visualstudio.com/items?itemName=matangover.mypy)\n* [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)\n\n### Releasing\n\nIt is only possible to release a _final version_ on the `master` branch. For it to pass the gates of the `publish` workflow, it must have the same version in the `tag`, the `setup.cfg`, the `bring_api/__init__.py` and an entry in the `CHANGELOG.md` file.\n\nTo release a prerelease version, no changelog entry is required, but it can only happen on a feature branch (**not** `master` branch). Also, prerelease versions are marked as such in the github release page.\n\n## Credits\n\nThis is a detached fork from the repo <https://github.com/skullydazed/docker2mqtt>, which does not seem to get evolved anymore.\n\n# CHANGELOG\n\n## 2.1.0\n\n* Update version package identifier and bump setuptools\n* Fix mypy setup\n\n## 2.0.5\n\n* Re-release due to bad deploy pipeline\n\n## 2.0.4\n\n* Update the discovery jsons for home assistant\n\n## 2.0.3\n\n* Transform the mqtt port cli arg to int as a str is not accepted by the paho.mqtt library\n* Fix the container filter not only at startup but also at runtime\n\n## 2.0.2\n\n* Add version cli options to display package version\n* Separate the entrypoints for cli (using cli arguments) and docker (using env vars)\n\n## 2.0.1\n\n* Fix white- and blacklist config via docker env where and empty string resulted in a pass-all regex overwriting the blacklist.\n\n## 2.0.0\n\n* Rework of the complete structure, but no functional changes.\n",
"bugtrack_url": null,
"license": null,
"summary": "Send your docker stats and and events to mqtt and discovery them in home assistant.",
"version": "2.1.0",
"project_urls": {
"Homepage": "https://github.com/miaucl/docker2mqtt"
},
"split_keywords": [
"mqtt",
" paho",
" docker",
" metrics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4ce2ddffe88401c653af58b354d8a25cedae428c183450d9bd91d3b6a1a73f77",
"md5": "8f6cfe917ca430749b29b6f096fd99a0",
"sha256": "bc887c238a40c6e5682447a370d07f6849f9db4a37fa79d6f5522e547f5d5912"
},
"downloads": -1,
"filename": "docker2mqtt-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8f6cfe917ca430749b29b6f096fd99a0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 21849,
"upload_time": "2024-09-19T18:01:09",
"upload_time_iso_8601": "2024-09-19T18:01:09.521850Z",
"url": "https://files.pythonhosted.org/packages/4c/e2/ddffe88401c653af58b354d8a25cedae428c183450d9bd91d3b6a1a73f77/docker2mqtt-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e559aaefa5787670d3833823f0edb317c54847aa695a95efc55dd5c41241a960",
"md5": "c86f1aa41e15737c1451e35d58536ceb",
"sha256": "11cfd39372f45adec064db54c99b75d2a6d9c288a0170e36c41c1ad68c0640f3"
},
"downloads": -1,
"filename": "docker2mqtt-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "c86f1aa41e15737c1451e35d58536ceb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 24599,
"upload_time": "2024-09-19T18:01:10",
"upload_time_iso_8601": "2024-09-19T18:01:10.911991Z",
"url": "https://files.pythonhosted.org/packages/e5/59/aaefa5787670d3833823f0edb317c54847aa695a95efc55dd5c41241a960/docker2mqtt-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-19 18:01:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "miaucl",
"github_project": "docker2mqtt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "paho-mqtt",
"specs": []
}
],
"lcname": "docker2mqtt"
}
JSON
