Skip to main content
Version: 9.x

Home Assistant (MQTT Auto-Discovery)

The Home Assistant MQTT integration provides native Update entities, device topology, and one-click container installations.

🏠 Home Assistant Integration​

WUD integrates deeply with Home Assistant via MQTT Auto-Discovery. This is the recommended and most feature-rich way to connect WUD to Home Assistant.

services:
  whatsupdocker:
    image: getwud/wud
    environment:
      - WUD_TRIGGER_MQTT_HASS_URL=mqtt://homeassistant.local:1883
      - WUD_TRIGGER_MQTT_HASS_HASS_ENABLED=true
      - WUD_TRIGGER_MQTT_HASS_HASS_DISCOVERY=true

🔄 Update Entity & One-Click Install​

Containers are exposed in Home Assistant as native update entities (e.g. update.wud_local_my_container):

  • Installed Version: Displays the current image tag (or digest).
  • Latest Version: Displays the available update tag (or truncated digest for digest-based updates).
  • Update Action ("Install" button): When clicking Install on an update entity in Home Assistant, an MQTT command is sent to WUD via command_topic ({topic}/{watcher}/{container}/install with payload INSTALL).
  • In-Progress State: WUD sets in_progress: true while the update runs, triggers the update trigger associated with the container (see below), and resets in_progress: false once completed.
Requirements for One-Click Install

To enable the Install button to perform container updates, make sure you have configured an update-capable trigger such as:

Choosing which trigger the Install button runs​

The Install button fires exactly one associated trigger per container, the same one the web UI's own Update dialog would default to: it prefers a docker/docker-compose trigger when one is associated with the container, otherwise it falls back to whichever other update-capable trigger (command, nomad) is associated.

"Associated" honors the same wud.trigger.include / wud.trigger.exclude container labels used everywhere else in WUD. This matters if the built-in docker/docker-compose update logic isn't correct for a given container — for example, a compose stack that needs a custom script to decrypt secrets before running docker compose up -d. In that case, associate a Command Trigger with the container and exclude the default docker/docker-compose trigger so the Install button runs your script instead:

services:
  my-app:
    image: my-app
    labels:
      - wud.trigger.exclude=dockercompose.default

With that label, the Install button (and the web UI's Update dialog) will resolve to the container's command trigger instead of the excluded dockercompose.default trigger.

Multiple associated triggers of the same priority

If a container ends up with more than one non-docker/docker-compose trigger associated at once (e.g. two command triggers, neither excluded), the Install button picks whichever one sorts first alphabetically by {type}.{name} — the same tie-break the web UI's Update dialog uses. This is a deterministic rule, but not necessarily an obvious one, so if you have more than one candidate trigger for a container, use wud.trigger.include/wud.trigger.exclude to name the one you want explicitly rather than relying on alphabetical ordering.

📦 Device Topology (Per-Watcher Devices)​

To keep Home Assistant devices organized and clean:

  • Watcher Devices: Each watcher gets its own dedicated device (e.g. wud (local) for a watcher named local). All containers monitored by this watcher are grouped under this device.
  • Global WUD Device: Represents the core WUD service, providing connection status (binary_sensor), total container count (sensor), total update count (sensor), and global update status (binary_sensor).
Migrating from Previous Versions

When upgrading to this version, if the legacy monolithic wud device already exists in Home Assistant, it is recommended to delete it from the Home Assistant UI (Settings > Devices & services > MQTT > wud device > Delete). Home Assistant will then cleanly rediscover the new per-watcher devices (wud_<watcher>) alongside the global wud device without orphan entities or duplicates.

📋 Summary Mode (Lite Integration)​

On larger setups with many containers or watchers, exposing individual Home Assistant update entities can flood the Settings > Updates panel, entity registry, and recorder.

To avoid this entity explosion while still getting full visibility into available updates, set WUD_TRIGGER_MQTT_{trigger_name}_HASS_ENTITIES=summary:

  • Summary topic ({topic}/updates): Publishes a retained JSON array of all containers that currently have an update available. If no updates are pending, publishes an empty array ([]). Each item includes:
    • name: Container name
    • displayName: Container display name (falls back to name)
    • watcher: Watcher name
    • stack: Compose project / stack name (if known)
    • kind: Update kind (tag or digest)
    • localValue: Currently deployed tag or digest
    • remoteValue: Newly available tag or digest
    • semverDiff: SemVer change type (major, minor, patch, prerelease, if applicable)
    • link: Release notes / repository link (if available)
  • Single Summary Sensor (sensor.wud_updates): Discovers a single sensor with:
    • State: Total count of pending updates ({topic}/update_count).
    • Attributes (json_attributes_topic): The list of pending updates under the updates attribute (e.g. state_attr('sensor.wud_updates', 'updates')).
  • Global Sensors Kept: The global connection status (binary_sensor.wud_container_status), total container count (sensor.wud_container_total_count), total update count (sensor.wud_container_update_count), and update status (binary_sensor.wud_container_update_status) continue to be discovered and updated.
  • Skipped & Cleaned Up Entities: Per-container update entities and per-watcher devices/sensors are omitted. If switching from all to summary mode, their discovery topics are automatically deleted.

🔐 MQTT Permissions & Broker ACLs​

When using an MQTT broker with Access Control Lists (ACLs) enabled (e.g. Mosquitto):

  • Read & Write on WUD Topics: WUD requires both publish and subscribe permissions on {topic}/# (by default wud/container/#) to publish container states and listen for install commands on {topic}/+/+/install.
  • Write on Discovery Topics: WUD needs publish permissions on {prefix}/# (by default homeassistant/#) to register entities via auto-discovery and publish empty retained tombstones when containers are removed.

⚙️ Configuration Variables​

The Home Assistant integration uses the underlying MQTT trigger. You can use all MQTT generic configuration options.

Here are the variables specifically relevant to Home Assistant:

WUD_TRIGGER_MQTT_{trigger_name}_HASS_DEVICEID
Optionalstringdefault: wud

Device identifier in Home Assistant

WUD_TRIGGER_MQTT_{trigger_name}_HASS_DEVICENAME
Optionalstringdefault: wud

Device display name in Home Assistant

WUD_TRIGGER_MQTT_{trigger_name}_HASS_DISCOVERY
Optionalbooleandefault: true (when HASS_ENABLED=true)

Enable Home Assistant MQTT Auto-Discovery. Defaults to true when HASS_ENABLED=true (false when HASS_ENABLED=false).

WUD_TRIGGER_MQTT_{trigger_name}_HASS_ENABLED
Optionalbooleandefault: false

Enable Home Assistant integration and publish state updates

WUD_TRIGGER_MQTT_{trigger_name}_HASS_ENTITIES
Optionalstringdefault: all

Discovery entities mode (all or summary). In all mode (default), discovers individual container update entities and per-watcher devices/sensors. In summary mode, discovers a single summary sensor (sensor.wud_updates) with pending updates list in attributes, plus global counts/status.

WUD_TRIGGER_MQTT_{trigger_name}_HASS_PREFIX
Optionalstringdefault: homeassistant

MQTT discovery prefix topic for Home Assistant

Customizing Entity Names & Icons in Home Assistant

You can customize how containers display in Home Assistant using the wud.display.name and wud.display.icon labels.