updates2mqtt 1.6.0__py3-none-any.whl

updates2mqtt-1.6.0.dist-info/METADATA

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: updates2mqtt
+Version: 1.6.0
+Summary: System update and docker image notification and execution over MQTT
+Keywords: mqtt,docker,updates,automation,home-assistant,homeassistant,selfhosting
+Author: jey burrows
+Author-email: jey burrows <jrb@rhizomatics.org.uk>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: Other/Proprietary License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Home Automation
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: System :: Monitoring
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Typing :: Typed
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: docker>=7.1.0
+Requires-Dist: paho-mqtt>=2.1.0
+Requires-Dist: omegaconf>=2.3.0
+Requires-Dist: structlog>=25.4.0
+Requires-Dist: rich>=14.0.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: hishel[httpx]>=0.1.4
+Requires-Dist: usingversion>=0.1.2
+Requires-Python: >=3.13
+Project-URL: Changelog, https://github.com/rhizomatics/updates2mqtt/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://updates2mqtt.rhizomatics.org.uk
+Project-URL: Homepage, https://updates2mqtt.rhizomatics.org.uk
+Project-URL: Issues, https://github.com/rhizomatics/updates2mqtt/issues
+Project-URL: Repository, https://github.com/rhizomatics/updates2mqtt
+Description-Content-Type: text/markdown
+
+![updates2mqtt](images/updates2mqtt-dark-256x256.png){ align=left }
+
+# updates2mqtt
+
+[![Rhizomatics Open Source](https://img.shields.io/badge/rhizomatics%20open%20source-lightseagreen)](https://github.com/rhizomatics)
+
+[![PyPI - Version](https://img.shields.io/pypi/v/updates2mqtt)](https://pypi.org/project/updates2mqtt/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/rhizomatics/updates2mqtt)
+[![Coverage](https://raw.githubusercontent.com/rhizomatics/updates2mqtt/refs/heads/badges/badges/coverage.svg)](https://updates2mqtt.rhizomatics.org.uk/developer/coverage/)
+![Tests](https://raw.githubusercontent.com/rhizomatics/updates2mqtt/refs/heads/badges/badges/tests.svg)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/rhizomatics/updates2mqtt/main.svg)](https://results.pre-commit.ci/latest/github/rhizomatics/updates2mqtt/main)
+[![Publish Python 🐍 distribution 📦 to PyPI and TestPyPI](https://github.com/rhizomatics/updates2mqtt/actions/workflows/pypi-publish.yml/badge.svg)](https://github.com/rhizomatics/updates2mqtt/actions/workflows/pypi-publish.yml)
+[![Github Deploy](https://github.com/rhizomatics/updates2mqtt/actions/workflows/python-package.yml/badge.svg?branch=main)](https://github.com/rhizomatics/updates2mqtt/actions/workflows/python-package.yml)
+[![CodeQL](https://github.com/rhizomatics/updates2mqtt/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/rhizomatics/updates2mqtt/actions/workflows/github-code-scanning/codeql)
+[![Dependabot Updates](https://github.com/rhizomatics/updates2mqtt/actions/workflows/dependabot/dependabot-updates/badge.svg)](https://github.com/rhizomatics/updates2mqtt/actions/workflows/dependabot/dependabot-updates)
+
+
+<br/>
+<br/>
+
+
+## Summary
+
+Let Home Assistant tell you about new updates to Docker images for your containers.
+
+![Example Home Assistant update page](images/ha_update_detail.png "Home Assistant Updates")
+
+Read the release notes, and optionally click *Update* to trigger a Docker *pull* (or optionally *build*) and *update*.
+
+![Example Home Assistant update dialog](images/ha_update_dialog.png "Home Assistant Updates"){width=480}
+
+
+## Description
+
+Updates2MQTT perioidically checks for new versions of components being available, and publishes new version info to MQTT. HomeAssistant auto discovery is supported, so all updates can be seen in the same place as Home Assistant's own components and add-ins.
+
+Currently only Docker containers are supported, either via an image registry check, or a git repo for source (see [Local Builds](local_builds.md)). The design is modular, so other update sources can be added, at least for notification. The next anticipated is **apt** for Debian based systems.
+
+Components can also be updated, either automatically or triggered via MQTT, for example by hitting the *Install* button in the HomeAssistant update dialog. Icons and release notes can be specified for a better HA experience. See [Home Assistant Integration](home_assistant.md) for details.
+
+To get started, read the [Installation](installation.md) and [Configuration](configuration.md) pages.
+
+For a quick spin, try this:
+
+```bash
+docker run -v /var/run/docker.sock:/var/run/docker.sock -e MQTT_USER=user1 -e MQTT_PASS=user1 -e MQTT_HOST=192.168.1.5 ghcr.io/rhizomatics/updates2mqtt:release
+```
+
+or without Docker, using [uv](https://docs.astral.sh/uv/)
+
+```bash
+export MQTT_HOST=192.168.1.1;export MQTT_USER=user1;export MQTT_PASS=user1;uv run --with updates2mqtt python -m updates2mqtt
+```
+
+## Release Support
+
+Presently only Docker containers are supported, although others are planned, probably with priority for `apt`.
+
+| Ecosystem | Support     | Comments                                                                                           |
+|-----------|-------------|----------------------------------------------------------------------------------------------------|
+| Docker    | Scan. Fetch | Fetch is ``docker pull`` only. Restart support only for ``docker-compose`` image based containers. |
+  
+## Heartbeat
+
+A heartbeat JSON payload is optionally published periodically to a configurable MQTT topic, defaulting to `healthcheck/{node_name}/updates2mqtt`. It contains the current version of Updates2MQTT, the node name, a timestamp, and some basic stats.
+
+## Healthcheck
+
+A `healthcheck.sh` script is included in the Docker image, and can be used as a Docker healthcheck, if the container environment variables are set for `MQTT_HOST`, `MQTT_PORT`, `MQTT_USER` and `MQTT_PASS`. It uses the `mosquitto-clients` Linux package which provides `mosquitto_sub` command to subscribe to topics.
+
+!!! tip
+
+    Check healthcheck is working using `docker inspect --format "{{json .State.Health }}" updates2mqtt | jq` (can omit `| jq` if you don't have jsonquery installed, but much easier to read with it)
+
+Another approach is using a restarter service directly in Docker Compose to force a restart, in this case once a day:
+
+```yaml title="Example Compose Service"
+restarter:
+    image: docker:cli
+    volumes: ["/var/run/docker.sock:/var/run/docker.sock"]
+    command: ["/bin/sh", "-c", "while true; do sleep 86400; docker restart updates2mqtt; done"]
+    restart: unless-stopped
+    environment:
+      - UPD2MQTT_UPDATE=AUTO
+```
+
+## Target Containers
+
+While `updates2mqtt` will discover and monitor all containers running under the Docker daemon,
+there are some options to make to those containers to tune how it works.
+
+These happen by adding environment variables to the containers, typically inside an `.env`
+file, or as `environment` options inside `docker-compose.yaml`.
+
+### Automated updates
+
+If Docker containers should be immediately updated, without any confirmation
+or trigger, *e.g.* from the HomeAssistant update dialog, then set an environment variable `UPD2MQTT_UPDATE` in the target container to `Auto` ( it defaults to `Passive`)
+
+```yaml title="Example Compose Snippet"
+restarter:
+    image: docker:cli
+    command: ["/bin/sh", "-c", "while true; do sleep 86400; docker restart mailserver; done"]
+    environment:
+      - UPD2MQTT_UPDATE=AUTO
+```
+
+This can be used in conjunction with the `UPD2MQTT_VERSION_INCLUDE` and `UPD2MQTT_VERSION_EXCLUDE` to
+limit which updates get automatically applied, for example excluding nightly builds.
+
+Automated updates can also apply to local builds, where a `git_repo_path` has been defined - if there are remote
+commits available to pull, then a `git pull`, `docker compose build` and `docker compose up` will be executed.
+
+### Environment Variables
+
+The following environment variables can be used to configure containers for `updates2mqtt`:
+
+| Env Var                    | Description                                                                                  | Default         |
+|----------------------------|----------------------------------------------------------------------------------------------|-----------------|
+| `UPD2MQTT_UPDATE`          | Update mode, either `Passive` or `Auto`. If `Auto`, updates will be installed automatically. | `Passive`       |
+| `UPD2MQTT_PICTURE`         | URL to an icon to use in Home Assistant.                                                     | Docker logo URL |
+| `UPD2MQTT_RELNOTES`        | URL to release notes for the package.                                                        |                 |
+| `UPD2MQTT_GIT_REPO_PATH`   | Relative path to a local git repo if the image is built locally.                             |                 |
+| `UPD2MQTT_IGNORE`          | If set to `True`, the container will be ignored by Updates2MQTT.                             | False           |
+| `UPD2MQTT_VERSION_INCLUDE` | Only recognize versions matching this string or regular expression                           |                 |
+| `UPD2MQTT_VERSION_EXCLUDE` | Skip update if version matches this string or regular expression                             |                 |
+
+### Docker Labels
+
+Alternatively, use Docker labels
+
+| Label                          | Env Var                    |
+|--------------------------------|----------------------------|
+| `updates2mqtt.update`          | `UPD2MQTT_UPDATE`          |
+| `updates2mqtt.picture`         | `UPD2MQTT_PCITURE`         |
+| `updates2mqtt.relnotes`        | `UPD2MQTT_RELNOTES`        |
+| `updates2mqtt.git_repo_path`   | `UPD2MQTT_GIT_REPO_PATH`   |
+| `updates2mqtt.ignore`          | `UPD2MQTT_IGNORE`          |
+| `updates2mqtt.version_include` | `UPD2MQTT_VERSION_INCLUDE` |
+| `updates2mqtt.version_exclude` | `UPD2MQTT_VERSION_EXCLUDE` |
+
+
+```yaml title="Example Compose Snippet"
+restarter:
+    image: docker:cli
+    command: ["/bin/sh", "-c", "while true; do sleep 86400; docker restart mailserver; done"]
+    labels:
+        updates2mqtt.relnotes: https://component.my.com/release_notes
+```
+
+
+## Related Projects
+
+Other apps useful for self-hosting with the help of MQTT:
+
+- [psmqtt](https://github.com/eschava/psmqtt) - Report system health and metrics via MQTT
+
+Find more at [awesome-mqtt](https://github.com/rhizomatics/awesome-mqtt)
+
+For a more powerful Docker update manager, try [What's Up Docker](https://getwud.github.io/wud/)
+
+## Development
+
+This component relies on several open source packages:
+
+- [docker-py](https://docker-py.readthedocs.io/en/stable/) SDK for Python for access to Docker APIs
+- [Eclipse Paho](https://eclipse.dev/paho/files/paho.mqtt.python/html/client.html) MQTT client
+- [OmegaConf](https://omegaconf.readthedocs.io) for configuration and validation
+- [structlog](https://www.structlog.org/en/stable/) for structured logging and [rich](https://rich.readthedocs.io/en/stable/) for better exception reporting
+- [hishel](https://hishel.com/1.0/) for caching metadata
+- [httpx](https://www.python-httpx.org) for retrieving metadata
+- The Astral [uv](https://docs.astral.sh/uv/) and [ruff](https://docs.astral.sh/ruff/) tools for development and build
+- [pytest](https://docs.pytest.org/en/stable/) and supporting add-ins for automated testing
+- [usingversion](https://pypi.org/project/usingversion/) to log current version info

updates2mqtt-1.6.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+updates2mqtt/__init__.py,sha256=gnmHrLOSYc-N1-c5VG46OpNpoXEybKzYhEvFMm955P8,237
+updates2mqtt/__main__.py,sha256=HBF00oH5fhS33sI_CdbxNlaUvbIzuuGxwnRYdhHqx0M,194
+updates2mqtt/app.py,sha256=uTgGgZX0xT7ee2-AB7tWTV8zKmtZiIWXHInmP8mrYZs,9357
+updates2mqtt/config.py,sha256=VN594apCjeUAwCekl0ItEMx-4eSeJsZIamHzsKoS0Ns,6136
+updates2mqtt/hass_formatter.py,sha256=6UfBhQLmFEYVVct_JeepIERwNvdwM2z8jkHAv-vOWa0,3191
+updates2mqtt/integrations/__init__.py,sha256=KmNTUxvVWvqI7rl4I0xZg7XaCmcMS2O4OSv-ClsWM4Q,109
+updates2mqtt/integrations/docker.py,sha256=3BQWgAENaoZjmJizrv_yHc3L6GXn8iQuUAXLcrXCS6g,28079
+updates2mqtt/integrations/git_utils.py,sha256=ODCKecWnom1NEKsmDZ2vFmYfnVGtWUgq7svVGcOtSaU,4369
+updates2mqtt/model.py,sha256=YkJyeoEgO1ApqEfcCmeMu9ROk9tOZPYxGx2oBkbXyy0,4657
+updates2mqtt/mqtt.py,sha256=W5kerew922CwaPvaNczVm61bvh3DGJ3k41BNZ1WJuuE,14987
+updates2mqtt/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+updates2mqtt-1.6.0.dist-info/WHEEL,sha256=eycQt0QpYmJMLKpE3X9iDk8R04v2ZF0x82ogq-zP6bQ,79
+updates2mqtt-1.6.0.dist-info/entry_points.txt,sha256=Nt1kQQfJ1M2RvcRUnVxe3KCMiX8puHPqz-D7BwqV1L8,55
+updates2mqtt-1.6.0.dist-info/METADATA,sha256=iVHtji5oJMxb05RD5rSoECjIgD_Bk6aa_vGwBQuCoyI,11769
+updates2mqtt-1.6.0.dist-info/RECORD,,

updates2mqtt-1.6.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.24
+Root-Is-Purelib: true
+Tag: py3-none-any

updates2mqtt-1.6.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+updates2mqtt = updates2mqtt.app:run
+