updates2mqtt 1.3.7__py3-none-any.whl → 1.4.0__py3-none-any.whl

updates2mqtt/config.py

@@ -16,6 +16,7 @@ class MqttConfig:
     password: str = f"${{oc.env:MQTT_PASS,{MISSING}}}"
     port: int = "${oc.decode:${oc.env:MQTT_PORT,1883}}"  # type: ignore[assignment]
     topic_root: str = "updates2mqtt"
+    protocol: str = "3.11"
 
 
 @dataclass

updates2mqtt/integrations/docker.py

@@ -287,7 +287,7 @@ class DockerProvider(ReleaseProvider):
                 logger.info(f"Shutdown detected, aborting scan at {c}")
                 break
             containers = containers + 1
-            result = self.analyze(cast("Container", c), session)
+            result = self.analyze(c, session)
             if result:
                 self.discoveries[result.name] = result
                 results = results + 1

updates2mqtt/integrations/git_utils.py

@@ -28,8 +28,10 @@ def git_timestamp(repo_path: Path, git_path: Path) -> datetime.datetime | None:
             check=True,
         )
         return datetime.datetime.fromisoformat(result.stdout.strip())
+    except subprocess.CalledProcessError as cpe:
+        log.warn("GIT No result from git log at %s: %s", repo_path, cpe)
     except Exception as e:
-        log.warn("GIT Unable to parse timestamp at %s - %s: %s", repo_path, result.stdout if result else "<NO RESULT>", e)
+        log.error("GIT Unable to parse timestamp at %s - %s: %s", repo_path, result.stdout if result else "<NO RESULT>", e)
     return None
 
 

updates2mqtt/mqtt.py

@@ -9,8 +9,8 @@ from typing import Any
 import paho.mqtt.client as mqtt
 import paho.mqtt.subscribeoptions
 import structlog
-from paho.mqtt.client import MQTTMessage
-from paho.mqtt.enums import CallbackAPIVersion, MQTTErrorCode
+from paho.mqtt.client import MQTT_CLEAN_START_FIRST_ONLY, MQTTMessage
+from paho.mqtt.enums import CallbackAPIVersion, MQTTErrorCode, MQTTProtocolVersion
 from paho.mqtt.properties import Properties
 from paho.mqtt.reasoncodes import ReasonCode
 
@@ -42,19 +42,39 @@ class MqttClient:
     def start(self, event_loop: asyncio.AbstractEventLoop | None = None) -> None:
         logger = self.log.bind(action="start")
         try:
+            protocol: MQTTProtocolVersion
+            if self.cfg.protocol in ("3", "3.11"):
+                protocol = MQTTProtocolVersion.MQTTv311
+            elif self.cfg.protocol == "3.1":
+                protocol = MQTTProtocolVersion.MQTTv31
+            elif self.cfg.protocol in ("5", "5.0"):
+                protocol = MQTTProtocolVersion.MQTTv5
+            else:
+                self.log.info("No valid MQTT protocol version found (%s), setting to default v3.11", self.cfg.protocol)
+                protocol = MQTTProtocolVersion.MQTTv311
+            self.log.debug("MQTT protocol set to %r", protocol)
+
             self.event_loop = event_loop or asyncio.get_event_loop()
             self.client = mqtt.Client(
                 callback_api_version=CallbackAPIVersion.VERSION2,
                 client_id=f"updates2mqtt_{self.node_cfg.name}",
-                clean_session=True,
+                clean_session=True if protocol != MQTTProtocolVersion.MQTTv5 else None,
+                protocol=protocol,
             )
             self.client.username_pw_set(self.cfg.user, password=self.cfg.password)
-            rc: MQTTErrorCode = self.client.connect(host=self.cfg.host, port=self.cfg.port, keepalive=60)
+            rc: MQTTErrorCode = self.client.connect(
+                host=self.cfg.host,
+                port=self.cfg.port,
+                keepalive=60,
+                clean_start=MQTT_CLEAN_START_FIRST_ONLY,
+            )
             self.log.info("Client connection requested", result_code=rc)
 
             self.client.on_connect = self.on_connect
             self.client.on_disconnect = self.on_disconnect
             self.client.on_message = self.on_message
+            self.client.on_subscribe = self.on_subscribe
+            self.client.on_unsubscribe = self.on_unsubscribe
 
             self.client.loop_start()
 
@@ -223,6 +243,30 @@ class MqttClient:
         )
         self.handle_message(msg)
 
+    def on_subscribe(
+        self,
+        _client: mqtt.Client,
+        userdata: Any,
+        mid: int,
+        reason_code_list: list[ReasonCode],
+        properties: Properties | None = None,
+    ) -> None:
+        self.log.debug(
+            "on_subscribe, userdata=%s, mid=%s, reasons=%s, properties=%s", userdata, mid, reason_code_list, properties
+        )
+
+    def on_unsubscribe(
+        self,
+        _client: mqtt.Client,
+        userdata: Any,
+        mid: int,
+        reason_code_list: list[ReasonCode],
+        properties: Properties | None = None,
+    ) -> None:
+        self.log.debug(
+            "on_unsubscribe, userdata=%s, mid=%s, reasons=%s, properties=%s", userdata, mid, reason_code_list, properties
+        )
+
     def on_message(self, _client: mqtt.Client, _userdata: Any, msg: mqtt.MQTTMessage) -> None:
         """Callback for incoming MQTT messages"""  # noqa: D401
         if msg.topic in self.providers_by_topic:

{updates2mqtt-1.3.7.dist-info → updates2mqtt-1.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: updates2mqtt
-Version: 1.3.7
+Version: 1.4.0
 Summary: System update and docker image notification and execution over MQTT
 Project-URL: Homepage, https://updates2mqtt.rhizomatics.org.uk
 Project-URL: Repository, https://github.com/rhizomatics/updates2mqtt
@@ -49,9 +49,14 @@ Description-Content-Type: text/markdown
 
 ## Summary
 
-Use Home Assistant to notify you of updates to Docker images for your containers and optionally perform the *pull* (or optionally *build*) and *update*.
+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}
 
-![Example Home Assistant update dialog](images/ha_update_detail.png "Home Assistant Updates")
 
 ## Description
 
@@ -59,7 +64,7 @@ updates2mqtt perioidically checks for new versions of components being available
 
 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.
+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.
 
@@ -71,8 +76,7 @@ docker run -e MQTT_USER=user1 -e MQTT_PASS=pass1 -e MQTT_HOST=192.168.1.5 ghcr.i
 
 ## Release Support
 
-Presently only Docker containers are supported, although others are planned,
-probably with priority for `apt`.
+Presently only Docker containers are supported, although others are planned, probably with priority for `apt`.
 
 | Ecosystem | Support     | Comments                                                                                           |
 |-----------|-------------|----------------------------------------------------------------------------------------------------|
@@ -82,31 +86,57 @@ probably with priority for `apt`.
 
 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.
 
-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`.
+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`
-  
-## HomeAssistant integration
+!!! tip
+
+    Check healthcheck is working using `docker inspect --format "{{json .State.Health }}" updates2mqtt | jq`
+
+Another approach is using a restarter service directly in Docker Compose to force a restart, in this case once a day:
 
-Any updates that have support for automated install will automatically show in the
-Home Assistant settings page if the [MQTT Integration](https://www.home-assistant.io/integrations/mqtt/) is installed and automatic discovery is not disabled.
+```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.
 
-![Home Assistant MQTT Integraion configuration](images/ha_mqtt_discovery.png "Home Assistant MQTT Discovery")
+These happen by adding environment variables to the containers, typically inside an `.env`
+file, or as `environment` options inside `docker-compose.yaml`.
 
-The `homeassistant` default topic prefix matches the default updates2mqtt config, if its changed in HomeAssistant, then the updates2mqtt config must be changed to match.
+### Automated updates
 
-![Home Assistant updates in Settings](images/ha_update_page.png "Home Assistant 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`)
 
-For Home Assistant integration, updates2mqtt represents each component being managed as a [MQTT Update](https://www.home-assistant.io/integrations/update.mqtt/) entity, and uses [MQTT discovery(https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery)] so that HomeAssistant automatically picks up components discovered by updates2mqtt with zero configuration on HomeAssistant itself. 
+```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
+```
+
+### Environment Variables
 
-There are 3 separate types of MQTT topic used for HomeAssisstant integration:
+The following environment variables can be used to configure containers for `updates2mqtt`:
 
-- *Config* to support auto discovery. A topic is created per component, with a name like `homeassistant/update/dockernuc_docker_jellyfin/update/config`. This can be disabled in the config file, and the `homeassistant` topic prefix can also be configured.
-- *State* to report the current version and the latest version available, again one topic per component, like `updates2mqtt/dockernuc/docker/jellyfin`.
-- *Command* to support triggering an update. These will be created on the fly by HomeAssistant when an update is requested, and updates2mqtt subscribes to pick up the changes, so you won't typically see these if browsing MQTT topics. Only one is needed per updates2mqtt agent, with a name like `updates2mqtt/dockernuc/docker`
+| 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 |
 
-If the package supports automated update, then *Skip* and *Install* buttons will appear on the Home Assistant
-interface, and the package can be remotely fetched and the component restarted.
 
 ## Related Projects
 
@@ -114,6 +144,18 @@ 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)
+
 ## Development
 
-Access to Docker APIs uses the Python [docker-py](https://docker-py.readthedocs.io/en/stable/) SDK for Python. [Eclipse Paho](https://eclipse.dev/paho/files/paho.mqtt.python/html/client.html) is used for MQTT access, and [OmegaConf](https://omegaconf.readthedocs.io) for configuration.
+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.4.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+updates2mqtt/__init__.py,sha256=gnmHrLOSYc-N1-c5VG46OpNpoXEybKzYhEvFMm955P8,237
+updates2mqtt/__main__.py,sha256=HBF00oH5fhS33sI_CdbxNlaUvbIzuuGxwnRYdhHqx0M,194
+updates2mqtt/app.py,sha256=7jnmtIkXlX4e4lIt8WCzV19IYrICkA7cU4m9u9QXvRU,8229
+updates2mqtt/config.py,sha256=SK6uhDyUb9C2JYVd0j6KBHzSAfaCFcOUbmmgsq6VSs0,5027
+updates2mqtt/hass_formatter.py,sha256=Ulfj8F0e_1QMmRuJzHsNM2WxHbz9sIkWOWjRq3kQZzs,2772
+updates2mqtt/model.py,sha256=5tWlj3appGGZjkuBeYR2lb-kXoy5mzCn4P_EJQjnwok,3676
+updates2mqtt/mqtt.py,sha256=LDy9x7Mmq_Em6lV-w9J3TjzBCuu8eehI8PK4E0i015A,14468
+updates2mqtt/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+updates2mqtt/integrations/__init__.py,sha256=KmNTUxvVWvqI7rl4I0xZg7XaCmcMS2O4OSv-ClsWM4Q,109
+updates2mqtt/integrations/docker.py,sha256=c1y3Xkv57_frxZOlq9LoYQRnfX-1XeedCjDcBLx1it0,18849
+updates2mqtt/integrations/git_utils.py,sha256=bPCmQiZpKpMcrGI7xAVmePXHFn8WwjcPNkf7xqDsGQA,2319
+updates2mqtt-1.4.0.dist-info/METADATA,sha256=0wYbNmGsu4nQF5C49M0pegMkpmMgW7rNR5n6FTbTwlA,8916
+updates2mqtt-1.4.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+updates2mqtt-1.4.0.dist-info/entry_points.txt,sha256=Hc6NZ2dBevYSUKTJU6NOs8Mw7Vt0S-9lq5FuKb76NCc,54
+updates2mqtt-1.4.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+updates2mqtt-1.4.0.dist-info/RECORD,,

{updates2mqtt-1.3.7.dist-info → updates2mqtt-1.4.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any

updates2mqtt-1.3.7.dist-info/RECORD

@@ -1,16 +0,0 @@
-updates2mqtt/__init__.py,sha256=gnmHrLOSYc-N1-c5VG46OpNpoXEybKzYhEvFMm955P8,237
-updates2mqtt/__main__.py,sha256=HBF00oH5fhS33sI_CdbxNlaUvbIzuuGxwnRYdhHqx0M,194
-updates2mqtt/app.py,sha256=7jnmtIkXlX4e4lIt8WCzV19IYrICkA7cU4m9u9QXvRU,8229
-updates2mqtt/config.py,sha256=NiaFdMTXXAjZIbtW7LHYjSqu-ONEoouT2uUu506CTtM,5000
-updates2mqtt/hass_formatter.py,sha256=Ulfj8F0e_1QMmRuJzHsNM2WxHbz9sIkWOWjRq3kQZzs,2772
-updates2mqtt/model.py,sha256=5tWlj3appGGZjkuBeYR2lb-kXoy5mzCn4P_EJQjnwok,3676
-updates2mqtt/mqtt.py,sha256=i2l1BlEmnkp3Ie2qeAPVmdhIO1I_mH8Zxbm84cIYtGI,12741
-updates2mqtt/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-updates2mqtt/integrations/__init__.py,sha256=KmNTUxvVWvqI7rl4I0xZg7XaCmcMS2O4OSv-ClsWM4Q,109
-updates2mqtt/integrations/docker.py,sha256=OX_sXtWVgUJfRSFi_tTBib4gvP_foQI4MoeTkTeLbZc,18868
-updates2mqtt/integrations/git_utils.py,sha256=SkAp6XcvCHwaiy17t6F97kcWTjBd7RyEmfhz6M_EhP0,2196
-updates2mqtt-1.3.7.dist-info/METADATA,sha256=yFJy-VGcnmHYdFksLx2teBHbuPi-B3J7pObaE5-XVEk,7990
-updates2mqtt-1.3.7.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-updates2mqtt-1.3.7.dist-info/entry_points.txt,sha256=Hc6NZ2dBevYSUKTJU6NOs8Mw7Vt0S-9lq5FuKb76NCc,54
-updates2mqtt-1.3.7.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-updates2mqtt-1.3.7.dist-info/RECORD,,