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_NOTIFICATION_MQTT_{trigger_name}_URL`	🔴	The URL of the MQTT broker	Valid mqtt, mqtts, tcp, tls, ws, wss url
`DD_NOTIFICATION_MQTT_{trigger_name}_USER`	⚪	The username if broker authentication is enabled
`DD_NOTIFICATION_MQTT_{trigger_name}_PASSWORD`	⚪	The password if broker authentication is enabled
`DD_NOTIFICATION_MQTT_{trigger_name}_CLIENTID`	⚪	The Mqtt client Id to use		`dd_$random`
`DD_NOTIFICATION_MQTT_{trigger_name}_TOPIC`	⚪	The base topic where the updates are published to		`dd/container`
`DD_NOTIFICATION_MQTT_{trigger_name}_HASS_ENABLED`	⚪	Enable Home-assistant integration and deliver additional topics	`true`, `false`	`false`
`DD_NOTIFICATION_MQTT_{trigger_name}_HASS_DISCOVERY`	⚪	Enable Home-assistant integration including discovery. When omitted, defaults to the value of `HASS_ENABLED`.	`true`, `false`	Same as `HASS_ENABLED`
`DD_NOTIFICATION_MQTT_{trigger_name}_HASS_PREFIX`	⚪	Base topic for hass entity discovery		`homeassistant`
`DD_NOTIFICATION_MQTT_{trigger_name}_HASS_AGENTTOPICSEGMENT`	⚪	Insert an `agent/<name>` segment into Home Assistant topics for containers owned by a remote agent, including watcher running-status topics, so multiple agents using the default watcher name `local` do not overwrite each other's topics. Recommended for multi-agent deployments. Controller-local container topics are unchanged. Targeted to become the default in v1.7.0.	`true`, `false`	`false`
`DD_NOTIFICATION_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_NOTIFICATION_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_NOTIFICATION_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_NOTIFICATION_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_NOTIFICATION_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_NOTIFICATION_MQTT_{trigger_name}_TLS_CLIENTCERT`	⚪	The path to the file containing the client public certificate (when TLS mutual authentication)	Any valid file path
`DD_NOTIFICATION_MQTT_{trigger_name}_TLS_CLIENTKEY`	⚪	The path to the file containing the client private key (when TLS mutual authentication)	Any valid file path
`DD_NOTIFICATION_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.

Home Assistant entity stability: When a watched container is recreated during an update, the MQTT HASS sensor (binary_sensor) is preserved without an intermediate unavailable/disappear state. Drydock sets a replacementExpected flag before stopping the old container so the entity remains visible in Home Assistant throughout the update.

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.

Multi-agent deployments: Home Assistant MQTT topics do not include an agent segment by default. If your controller and one or more agents all use the default watcher name local, two same-named containers on different agents publish to — and overwrite — the same topics, watcher running-status topics collide, and watcher-level sensor counts sum across agents. Set DD_NOTIFICATION_MQTT_{trigger_name}_HASS_AGENTTOPICSEGMENT=true to insert an agent/<name> segment for agent-owned containers (controller-local topics are unchanged). This changes the Home Assistant entity IDs for agent containers, so update any automations or dashboards that reference them. This corrected layout is targeted to become the default in v1.7.0 — see Deprecations.

Examples

Post a message to a local mosquitto broker

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

docker run \
    -e DD_NOTIFICATION_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_NOTIFICATION_MQTT_MOSQUITTO_URL=mqtts://localhost:8883
      - DD_NOTIFICATION_MQTT_MOSQUITTO_TLS_CLIENTKEY=/drydock/mqtt/client-key.pem
      - DD_NOTIFICATION_MQTT_MOSQUITTO_TLS_CLIENTCERT=/drydock/mqtt/client-cert.pem
      - DD_NOTIFICATION_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_NOTIFICATION_MQTT_MOSQUITTO_URL="mqtts://localhost:8883" \
    -e DD_NOTIFICATION_MQTT_MOSQUITTO_TLS_CLIENTKEY="/drydock/mqtt/client-key.pem" \
    -e DD_NOTIFICATION_MQTT_MOSQUITTO_TLS_CLIENTCERT="/drydock/mqtt/client-cert.pem" \
    -e DD_NOTIFICATION_MQTT_MOSQUITTO_TLS_CACHAIN="/drydock/mqtt/ca.pem" \
  ...
  codeswhat/drydock

Post a message to a maqiatto broker

services:
  drydock:
    image: codeswhat/drydock
    ...
    environment:
      - DD_NOTIFICATION_MQTT_MAQIATTO_URL=tcp://maqiatto.com:1883
      - DD_NOTIFICATION_MQTT_MAQIATTO_USER=john@doe.com
      - DD_NOTIFICATION_MQTT_MAQIATTO_PASSWORD=mysecretpassword
      - DD_NOTIFICATION_MQTT_MAQIATTO_TOPIC=john@doe.com/drydock/image

docker run \
    -e DD_NOTIFICATION_MQTT_MAQIATTO_URL="tcp://maqiatto.com:1883" \
    -e DD_NOTIFICATION_MQTT_MAQIATTO_USER="john@doe.com" \
    -e DD_NOTIFICATION_MQTT_MAQIATTO_PASSWORD="mysecretpassword" \
    -e DD_NOTIFICATION_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 integrates with Home Assistant via MQTT Discovery.

services:
  drydock:
    image: codeswhat/drydock
    ...
    environment:
      - DD_NOTIFICATION_MQTT_MOSQUITTO_URL=mqtt://localhost:1883
      - DD_NOTIFICATION_MQTT_MOSQUITTO_HASS_ENABLED=true
      - DD_NOTIFICATION_MQTT_MOSQUITTO_HASS_DISCOVERY=true

docker run \
    -e DD_NOTIFICATION_MQTT_MOSQUITTO_URL="mqtt://localhost:1883" \
    -e DD_NOTIFICATION_MQTT_MOSQUITTO_HASS_ENABLED="true" \
    -e DD_NOTIFICATION_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_NOTIFICATION_MQTT_{trigger_name}_HASS_FILTER_INCLUDE to keep only selected flattened keys.

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

Exclude mode (`HASS_FILTER_EXCLUDE`)

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

environment:
  - DD_NOTIFICATION_MQTT_MOSQUITTO_HASS_FILTER_EXCLUDE=security_sbom_documents_0_spdx_version,security_scan_vulnerabilities_0_id

Legacy nested exclude (`EXCLUDE`)

DD_NOTIFICATION_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