updates2mqtt 1.3.7__tar.gz → 1.4.0__tar.gz

{updates2mqtt-1.3.7 → updates2mqtt-1.4.0}/.github/dependabot.yml

@@ -9,16 +9,22 @@ updates:
     directory: "/" # Location of package manifests
     schedule:
       interval: "weekly"
+    cooldown:
+      default-days: 7
 
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
       interval: "monthly"
+    cooldown:
+      default-days: 7
 
   - package-ecosystem: "docker"
     directory: "/"
     schedule:
       interval: "weekly"
+    cooldown:
+      default-days: 7
 
 
 

{updates2mqtt-1.3.7 → updates2mqtt-1.4.0}/.github/workflows/docker-publish.yml

@@ -42,7 +42,7 @@ jobs:
         uses: docker/setup-buildx-action@v3
       - name: Extract metadata (tags, labels) for Docker
         id: meta
-        uses: docker/metadata-action@032a4b3bda1b716928481836ac5bfe36e1feaad6
+        uses: docker/metadata-action@8d8c7c12f7b958582a5cb82ba16d5903cb27976a
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |

{updates2mqtt-1.3.7 → updates2mqtt-1.4.0}/.github/workflows/pypi-publish.yml

@@ -22,7 +22,7 @@ jobs:
     - name: Build a binary wheel and a source tarball
       run: uv build
     - name: Store the distribution packages
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v5
       with:
         name: python-package-distributions
         path: dist/
@@ -42,7 +42,7 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v6
       with:
         name: python-package-distributions
         path: dist/
@@ -64,7 +64,7 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v6
       with:
         name: python-package-distributions
         path: dist/

{updates2mqtt-1.3.7 → updates2mqtt-1.4.0}/.github/workflows/python-package.yml

@@ -25,6 +25,7 @@ jobs:
         python-version-file: "pyproject.toml"
     - name: Install dependencies
       run: uv sync --all-extras --dev
+       
     - name: Ruff
       uses: chartboost/ruff-action@v1
     - name: Test with pytest
@@ -32,11 +33,12 @@ jobs:
     - name: Build a binary wheel and a source tarball
       run: uv build
     - name: Prep for mkdocs
-      run: uv pip compile pyproject.toml -o requirements_docs.txt --group mkdocs
+      run:  uv pip compile pyproject.toml -o requirements_docs.txt --group mkdocs
     - name: Deploy docs
       uses: mhausenblas/mkdocs-deploy-gh-pages@master
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        EXTRA_PACKAGES: pngquant
         REQUIREMENTS: requirements_docs.txt
         CUSTOM_DOMAIN: updates2mqtt.rhizomatics.org.uk
 

{updates2mqtt-1.3.7 → updates2mqtt-1.4.0}/.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/asottile/pyupgrade
-    rev: v3.21.1
+    rev: v3.21.2
     hooks:
       - id: pyupgrade
         args: [--py313-plus]
@@ -17,11 +17,11 @@ repos:
       - id: check-shebang-scripts-are-executable
         name: Check shell scripts are executable
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.9.9
+    rev: 0.9.13
     hooks:
       - id: uv-lock
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.4
+    rev: v0.14.7
     hooks:
      # Run the linter.
       - id: ruff-check
@@ -39,7 +39,7 @@ repos:
         exclude_types: [csv, json]
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.18.2
+    rev: v1.19.0
     hooks:
       - id: mypy
         args:
@@ -64,7 +64,7 @@ repos:
           - usingversion
  
   - repo: https://github.com/PyCQA/bandit
-    rev: '1.8.6'
+    rev: '1.9.2'
     hooks:
       - id: bandit
         args: ["-c", "pyproject.toml"]

{updates2mqtt-1.3.7 → updates2mqtt-1.4.0}/CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## 1.4.0
+- MQTT protocol can now be set, to one of `3.1`,`3.11` or `5`
+- Debug messages now provided for `on_subscribe` and `on_unsubscribe` callbacks
+- Troubleshooting, installation, configuration docs updated, images optimized
+
 ## 1.3.7
 - Improved initial setup when run without config or env vars for MQTT
 - Minor test deps update and pyproject docs

{updates2mqtt-1.3.7 → updates2mqtt-1.4.0}/Dockerfile

@@ -30,7 +30,7 @@ ADD scripts/healthcheck.sh /app
 RUN chmod ug+x /app/healthcheck.sh
 ADD README.md /app/README.md
 ADD common_packages.yaml /app
-
+RUN mkdir /app/.cache && chmod a+rw /app/.cache
 
 RUN uv sync --locked
 

{updates2mqtt-1.3.7 → updates2mqtt-1.4.0}/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,124 @@
+[![Rhizomatics Open Source](https://avatars.githubusercontent.com/u/162821163?s=96&v=4)](https://github.com/rhizomatics)
+
+# updates2mqtt
+
+[![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/supernotify)
+[![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)
+
+## 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:
+
+```yaml
+docker run -e MQTT_USER=user1 -e MQTT_PASS=pass1 -e MQTT_HOST=192.168.1.5 ghcr.io/rhizomatics/updates2mqtt:release
+```
+
+## 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. |
+  
+## Healthcheck
+
+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`. 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`
+
+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
+```
+
+### 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 |
+
+
+## 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)
+
+## 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.3.7 → updates2mqtt-1.4.0}/docs/configuration.md

@@ -4,7 +4,8 @@ Create file `config.yaml` in `conf` directory. If the file is not present, a def
 
 ### Example configuration file
 
-This is a maximal config file, the minimum is no config file at all, which will generate a default config file. The only mandatory values are the MQTT user name and password, everything else can be omitted.
+This is a maximal config file, the minimum is no config file at all, which will generate a default config file. The only mandatory values are the MQTT user name and password, everything else can be omitted ( although
+its best to have at least a `node` `name` value so HomeAssistant doesn't show some ugly generated Docker host name).
 
 ```yaml
 
@@ -21,6 +22,7 @@ mqtt:
   password: ${oc.env:MQTT_PASS}$ # Use an environment variable for secrets
   port: ${oc.env:MQTT_PORT}
   topic_root: updates2mqtt
+  protocol: 3.11 # Can be changed to 5 if your broker supports it
 homeassistant:
   discovery:
     prefix: homeassistant # Matches the default MQTT discovery prefix in Home Assistant
@@ -44,6 +46,8 @@ log:
   level: INFO
 ```
 
+## Improving Security
+
 ### Moving Secrets Out of Config
 
 Example use of environment variables, e.g. for secrets:
@@ -52,7 +56,50 @@ Example use of environment variables, e.g. for secrets:
 mqtt:
     password: ${oc.env:MQTT_PASS}
 ```
-### Customizing images and release notes
+
+### Running as non-root
+
+It is good practice not to run Docker containers as root, and `updates2mqtt` will
+work with any user so long as it has Docker permissions, usually as a result
+of being a member of the `docker` group.
+
+To create a suitable use, use the shell command below - it will create a user
+that can only be used for this purpose, and can't otherwise login. It assumes there is already a group called `docker` with access to the Docker Daemon, if you dont
+have one, follow the [Docker Post Install Steps](https://docs.docker.com/engine/install/linux-postinstall/) which explain how and why to do it.
+
+```bash
+sudo adduser --system --ingroup docker --no-create-home -shell /sbin/nologin updates2mqtt
+```
+
+Note the `uid` that is reported here. If you don't know the `gid` for the `docker` group, use `grep docker /etc/group`. In this example, our `uid` is `130` and the `gid` of `docker` group is `119`.
+
+In the `docker-compose.yaml`, set the user and group using [user](https://docs.docker.com/reference/compose-file/services/#user) attribute:
+
+```yaml
+services:
+  updates2mqtt:
+    container_name: updates2mqtt
+    image: ghcr.io/rhizomatics/updates2mqtt:release
+    user: 130:119
+```
+
+If you're using Updates2MQTT to update local git repos, then the user created above will also need `rw` access to those, which you can do by making it a member of the
+same group as owns the repos and making sure they have group `rw` access configured.
+
+For more information, see the [Understanding the Docker USER Instruction](https://www.docker.com/blog/understanding-the-docker-user-instruction/) article from Docker.
+
+### MQTT Access Control
+
+Its best to have a dedicated MQTT user for Updates2MQTT, for security and debug. For most
+secure installations, only use secure ports with validated certificates, although this will
+require more complicated setup and ongoing support, including using host names rather than
+IP addresses, and with [LetsEncrypt](https://letsencrypt.org) to update certificates.
+
+The two brokers most commonly used with Home Assistant, **Mosquitto** and **EMQX**, both have
+access control mechanisms, so you can restrict the user account for Updates2MQTT to only be able
+to read and write its own topics.
+
+## Customizing images and release notes
 
 Individual docker containers can have customized entity pictures or release notes, using env variables, for example in the `docker-compose.yaml` or in a separate `.env` file:
 
@@ -65,6 +112,7 @@ Individual docker containers can have customized entity pictures or release note
 The images will show up in the *Update* section of *Settings* menu in HomeAssistant,
 as will the release notes link. SVG icons should be used.
 
+
 #### Icon Sources
 
 Updates look nicer in Home Assistant with a suitable icon. Updates2mqtt comes
@@ -79,20 +127,3 @@ If you have something not covered, here are some good places to look for self-ho
 - [Papirus Icons](https://github.com/PapirusDevelopmentTeam/papirus-icon-theme)
 - [Homelab SVG Assets](https://github.com/loganmarchione/homelab-svg-assets)
 
-### 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`)
-
-
-### Environment Variables
-
-The following environment variables can be used to configure 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 |

updates2mqtt-1.4.0/docs/home_assistant.md

@@ -0,0 +1,34 @@
+# HomeAssistant 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. 
+
+## Configuration
+
+If Home Assistant is already running with MQTT, and the defaults haven't been changed, then
+`updates2mqtt` will likely work as is, so long as its publishing to the same broker.
+
+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.
+
+![Home Assistant MQTT Integration configuration](images/ha_mqtt_discovery.png "Home Assistant MQTT Discovery")
+
+The `homeassistant` default topic prefix matches the default updates2mqtt config, if its changed in HomeAssistant, then the updates2mqtt config must be changed to match.
+
+![Home Assistant updates in Settings](images/ha_update_page.png "Home Assistant Updates")
+
+## MQTT Topics
+
+There are 3 separate types of MQTT topic used for HomeAssisstant integration:
+
+- *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`
+
+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.
+
+## More Home Assistant information
+
+- [MQTT Integration](https://www.home-assistant.io/integrations/mqtt/)
+    - Includes setting up a MQTT broker, MQTT Discovery, and trouble-shooting
+- [MQTT Update](https://www.home-assistant.io/integrations/update.mqtt/)
+- [Update Integration](https://www.home-assistant.io/integrations/update/)

{updates2mqtt-1.3.7 → updates2mqtt-1.4.0}/docs/installation.md

@@ -4,6 +4,8 @@
 
 updates2mqtt prefers to be run inside a Docker container, though can run standalone, for example scripted via cron or systemd.
 
+The only mandatory configuration is the MQTT broker host, user name and password, which can be set by environment variable, or the config file. See [Configuration](configuration.md).
+
 ### Docker
 
 See `examples` directory for a working `docker-compose.yaml`.
@@ -27,3 +29,16 @@ uv run --with updates2mqtt updates2mqtt
 pip install updates2mqtt
 python3 -m updates2mqtt
 ```
+
+## Verifying it Works
+
+Rather than wait for a container to need an update, you can check right away that
+Home Assistant has recognized the containers as MQTT Update targets.
+
+From the [Entities View](https://www.home-assistant.io/docs/configuration/entities_domains/), or the
+[Developer Tools](https://www.home-assistant.io/docs/tools/dev-tools/), filter
+the entities by `update.` If there are lots of other updates (HassOS apps, Zigbee
+device firmware etc), then pick one of the container names you know.
+
+![Home Assistant Entities](images/ha_entities.png){width=640}
+