Mqtt

The mqtt trigger lets you send container update notifications to an MQTT broker.

logo

The mqtt trigger lets you send container update notifications to an MQTT broker.

Variables

Env var	Required	Description	Supported values	Default value when missing
`DD_TRIGGER_MQTT_{trigger_name}_URL`	🔴	The URL of the MQTT broker	Valid mqtt, mqtts, tcp, tls, ws, wss url
`DD_TRIGGER_MQTT_{trigger_name}_USER`	⚪	The username if broker authentication is enabled
`DD_TRIGGER_MQTT_{trigger_name}_PASSWORD`	⚪	The password if broker authentication is enabled
`DD_TRIGGER_MQTT_{trigger_name}_CLIENTID`	⚪	The Mqtt client Id to use		`dd_$random`
`DD_TRIGGER_MQTT_{trigger_name}_TOPIC`	⚪	The base topic where the updates are published to		`dd/container`
`DD_TRIGGER_MQTT_{trigger_name}_HASS_ENABLED`	⚪	Enable Home-assistant integration and deliver additional topics	`true`, `false`	`false`
`DD_TRIGGER_MQTT_{trigger_name}_HASS_DISCOVERY`	⚪	Enable Home-assistant integration including discovery	`true`, `false`	`false`
`DD_TRIGGER_MQTT_{trigger_name}_HASS_PREFIX`	⚪	Base topic for hass entity discovery		`homeassistant`
`DD_TRIGGER_MQTT_{trigger_name}_HASS_ATTRIBUTES`	⚪	Attribute preset controlling which container fields are included in MQTT payloads. `full` sends everything; `short` excludes large fields like SBOM documents, scan vulnerabilities, details, and labels.	`full`, `short`	`short`
`DD_TRIGGER_MQTT_{trigger_name}_HASS_FILTER_INCLUDE`	⚪	Comma-separated list of flattened MQTT attribute keys to keep (include-mode). When set, only these keys are published.	Comma-separated flattened keys
`DD_TRIGGER_MQTT_{trigger_name}_HASS_FILTER_EXCLUDE`	⚪	Comma-separated list of flattened MQTT attribute keys to remove (exclude-mode). Used when `HASS_FILTER_INCLUDE` is empty.	Comma-separated flattened keys
`DD_TRIGGER_MQTT_{trigger_name}_EXCLUDE`	⚪	Legacy comma-separated dot-paths to exclude from the nested container object before flattening. Used only when both `HASS_FILTER_INCLUDE` and `HASS_FILTER_EXCLUDE` are empty.	Comma-separated dot-paths
`DD_TRIGGER_MQTT_{trigger_name}_TLS_CACHAIN`	⚪	The path to the file containing the server CA chain (when TLS with a private Certificate Authority)	Any valid file path
`DD_TRIGGER_MQTT_{trigger_name}_TLS_CLIENTCERT`	⚪	The path to the file containing the client public certificate (when TLS mutual authentication)	Any valid file path
`DD_TRIGGER_MQTT_{trigger_name}_TLS_CLIENTKEY`	⚪	The path to the file containing the client private key (when TLS mutual authentication)	Any valid file path
`DD_TRIGGER_MQTT_{trigger_name}_TLS_REJECTUNAUTHORIZED`	⚪	Accept or reject when the TLS server certificate cannot be trusted	`true`, `false`	`true`

This trigger also supports the common configuration variables. but only supports the simple mode.

You want to customize the name & icon of the Home-Assistant entity? Use the dd.display.name and dd.display.icon labels.

For Home Assistant, the entity_picture is automatically derived from the dd.display.icon label. Icons with sh:, hl:, or si: prefixes map to CDN image URLs. You can also set dd.display.picture to provide a direct URL override.

Examples

Post a message to a local mosquitto broker

services:
  drydock:
    image: codeswhat/drydock
    ...
    environment:
      - DD_TRIGGER_MQTT_MOSQUITTO_URL=mqtt://localhost:1883

docker run \
    -e DD_TRIGGER_MQTT_MOSQUITTO_URL="mqtt://localhost:1883" \
  ...
  codeswhat/drydock

Post a message to a local mosquitto broker with mTLS enabled

services:
  drydock:
    image: codeswhat/drydock
    ...
    environment:
      - DD_TRIGGER_MQTT_MOSQUITTO_URL=mqtts://localhost:8883
      - DD_TRIGGER_MQTT_MOSQUITTO_TLS_CLIENTKEY=/drydock/mqtt/client-key.pem
      - DD_TRIGGER_MQTT_MOSQUITTO_TLS_CLIENTCERT=/drydock/mqtt/client-cert.pem
      - DD_TRIGGER_MQTT_MOSQUITTO_TLS_CACHAIN=/drydock/mqtt/ca.pem
    volumes:
      - /mosquitto/tls/client/client-key.pem:/drydock/mqtt/client-key.pem
      - /mosquitto/tls/client/client-cert.pem:/drydock/mqtt/client-cert.pem
      - /mosquitto/tls/ca.pem:/drydock/mqtt/ca.pem

docker run \
    -e DD_TRIGGER_MQTT_MOSQUITTO_URL="mqtts://localhost:8883" \
    -e DD_TRIGGER_MQTT_MOSQUITTO_TLS_CLIENTKEY="/drydock/mqtt/client-key.pem" \
    -e DD_TRIGGER_MQTT_MOSQUITTO_TLS_CLIENTCERT="/drydock/mqtt/client-cert.pem" \
    -e DD_TRIGGER_MQTT_MOSQUITTO_TLS_CACHAIN="/drydock/mqtt/ca.pem" \
  ...
  codeswhat/drydock

Post a message to a maqiatto broker

services:
  drydock:
    image: codeswhat/drydock
    ...
    environment:
      - DD_TRIGGER_MQTT_MAQIATTO_URL=tcp://maqiatto.com:1883
      - DD_TRIGGER_MQTT_MAQIATTO_USER=john@doe.com
      - DD_TRIGGER_MQTT_MAQIATTO_PASSWORD=mysecretpassword
      - DD_TRIGGER_MQTT_MAQIATTO_TOPIC=john@doe.com/drydock/image

docker run \
    -e DD_TRIGGER_MQTT_MAQIATTO_URL="tcp://maqiatto.com:1883" \
    -e DD_TRIGGER_MQTT_MAQIATTO_USER="john@doe.com" \
    -e DD_TRIGGER_MQTT_MAQIATTO_PASSWORD="mysecretpassword" \
    -e DD_TRIGGER_MQTT_MAQIATTO_TOPIC="john@doe.com/drydock/image" \
  ...
  codeswhat/drydock

Example of sent message

{
  "id": "31a61a8305ef1fc9a71fa4f20a68d7ec88b28e32303bbc4a5f192e851165b816",
  "name": "homeassistant",
  "watcher": "local",
  "image_id": "sha256:d4a6fafb7d4da37495e5c9be3242590be24a87d7edcc4f79761098889c54fca6",
  "image_registry_url": "123456789.dkr.ecr.eu-west-1.amazonaws.com",
  "image_name": "test",
  "image_tag_value": "2021.6.4",
  "image_tag_semver": true,
  "image_digest_watch": false,
  "image_digest_repo": "sha256:ca0edc3fb0b4647963629bdfccbb3ccfa352184b45a9b4145832000c2878dd72",
  "image_architecture": "amd64",
  "image_os": "linux",
  "image_created": "2021-06-12T05:33:38.440Z",
  "display_name": "Home Assistant",
  "display_icon": "sh:homeassistant",
  "result_tag": "2021.6.5",
  "update_available": true
}

Home-Assistant integration

logo

drydock can be easily integrated into Home-Assistant using MQTT Discovery.

services:
  drydock:
    image: codeswhat/drydock
    ...
    environment:
      - DD_TRIGGER_MQTT_MOSQUITTO_URL=mqtt://localhost:1883
      - DD_TRIGGER_MQTT_MOSQUITTO_HASS_ENABLED=true
      - DD_TRIGGER_MQTT_MOSQUITTO_HASS_DISCOVERY=true

docker run \
    -e DD_TRIGGER_MQTT_MOSQUITTO_URL="mqtt://localhost:1883" \
    -e DD_TRIGGER_MQTT_MOSQUITTO_HASS_ENABLED="true" \
    -e DD_TRIGGER_MQTT_MOSQUITTO_HASS_DISCOVERY="true" \
  ...
  codeswhat/drydock

Check that mqtt integration is properly configured

A drydock device is automatically added to the hass registry

Entities are automatically created (per Docker image)

Entities are binary_sensors whose state is true when an update is available.

Entities

Entities expose all the details of the container as attributes:

Current version
New version
Registry
Architecture
OS
Size
...

Attribute filtering

Container MQTT payloads can include large nested fields (SBOM documents, scan vulnerability arrays, environment details, labels) that exceed Home Assistant's json_attributes_topic size limits or clutter entity attributes.

Filtering is applied in this precedence order:

HASS_FILTER_INCLUDE (flattened key include list)
HASS_FILTER_EXCLUDE (flattened key exclude list)
EXCLUDE (legacy nested dot-path exclude list)
HASS_ATTRIBUTES preset fallback

Include mode (`HASS_FILTER_INCLUDE`)

Set DD_TRIGGER_MQTT_{trigger_name}_HASS_FILTER_INCLUDE to keep only selected flattened keys.

environment:
  - DD_TRIGGER_MQTT_MOSQUITTO_HASS_FILTER_INCLUDE=name,image_name,update_available,result_tag

Exclude mode (`HASS_FILTER_EXCLUDE`)

Set DD_TRIGGER_MQTT_{trigger_name}_HASS_FILTER_EXCLUDE to remove selected flattened keys.

environment:
  - DD_TRIGGER_MQTT_MOSQUITTO_HASS_FILTER_EXCLUDE=security_sbom_documents_0_spdx_version,security_scan_vulnerabilities_0_id

Legacy nested exclude (`EXCLUDE`)

DD_TRIGGER_MQTT_{trigger_name}_EXCLUDE still supports comma-separated nested dot-paths (for example security.sbom.documents,labels). This legacy filter is only used when HASS_FILTER_INCLUDE and HASS_FILTER_EXCLUDE are both empty.

Attribute preset fallback (`HASS_ATTRIBUTES`)

When no explicit include/exclude list is configured, HASS_ATTRIBUTES is used:

Preset	Behavior
`full`	Sends the entire container object — no filtering
`short` (default)	Excludes `security.sbom.documents`, `security.updateSbom.documents`, `security.scan.vulnerabilities`, `security.updateScan.vulnerabilities`, `details`, and `labels`

HASS_FILTER_INCLUDE and HASS_FILTER_EXCLUDE match flattened MQTT keys (snake_case + underscore delimiter), because filtering is applied after flattening to the payload shape Home Assistant receives.

Mqtt

On this page