updates2mqtt 1.7.2

System update and docker image notification and execution over MQTT

{ align=left }

updates2mqtt

Summary

Let Home Assistant tell you about new updates to Docker images for your containers.

{width=300}

Read the release notes, and optionally click Update to trigger a Docker pull (or optionally build) and update.

{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 (using either v1 Docker APIs or the OCI v2 API), or a git repo for source (see Local Builds), with specific handling for Docker, Github Container Registry, Gitlab, Codeberg, Microsoft Container Registry and LinuxServer Registry, with adaptive behaviour to cope with most others. 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 for details.

To get started, read the Installation and Configuration pages.

For a quick spin, try this:

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:latest

or without Docker, using uv

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:

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). If you want it to update without publishing to MQTT and being visible to Home Assistant, then use Silent.

restarter:
    image: docker:cli
    command: ["/bin/sh", "-c", "while true; do sleep 86400; docker restart mailserver; done"]
    environment:
      - UPD2MQTT_UPDATE=AUTO

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_POLICY | Change how version derived from container label or image hash, Version,Digest,Version_Digest with default of Auto| | UPD2MQTT_REGISTRY_TOKEN | Access token for authentication to container distribution API, as alternative to making a call to token service |

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_policy	UPD2MQTT_VERSION_POLICY
updates2mqtt.registry_token	UPD2MQTT_REGISTRY_TOKEN

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 - Report system health and metrics via MQTT

Find more at awesome-mqtt

For a more powerful Docker update manager, try What's Up Docker

Development

This component relies on several open source packages:

• docker-py SDK for Python for access to Docker APIs
• Eclipse Paho MQTT client
• OmegaConf for configuration and validation
• structlog for structured logging and rich for better exception reporting
• hishel for caching metadata
• httpx for retrieving metadata
• The Astral uv and ruff tools for development and build
• pytest and supporting add-ins for automated testing
• usingversion to log current version info