Version: 9.x

Container & Workload Customization

WUD allows you to fine-tune monitoring behavior on a per-workload basis using metadata attached directly to your containers, pods, or jobs.

Regardless of your orchestrator, the property names and logic are 100% identical:

Orchestrator	Metadata Type	Canonical Key Format	Supported Aliases
🐳 Docker / Compose	Container Labels	`wud.<property>`	—
🐝 Docker Swarm	Service Labels (`deploy.labels`)	`getwud.app/<property>`	`wud.<property>`, `wud/<property>`
☸️ Kubernetes	Workload Annotations	`getwud.app/<property>`	`wud/<property>`, `wud.getwud.io/<property>`
🟢 Nomad	Task / Group / Job Meta	`getwud.app/<property>`	`wud.<property>`, `wud/<property>`

Multi-Container Targeting

In orchestrators that support multi-container workloads (such as Kubernetes Pods or Nomad Task Groups):

Workload-level default: Set the property globally on the Deployment, StatefulSet, or Nomad Job/Group to apply to all containers.
Per-container override: Suffix the property with .<container_name> (or <task_name>) to target a specific container:
- Kubernetes: getwud.app/tag.include.nginx: "^1\\.27"
- Nomad: "getwud.app/tag.include.web" = "^1\\.27" (or place directly inside the task's meta {} block)

Available Properties

display.icon

Optionalstringdefault: mdi:docker

Custom display icon for the workload in the UI and integrations

Allowed values:Any Iconify icon (mdi, simple-icons, selfhst, logos, fa6, etc.) or image URL (HTTP/HTTPS/data:image/)

display.name

Optionalstringdefault: Container or Task name

Custom display name for the container in notifications and UI

Allowed values:Any string

link.changelog

Optionalstring

Link or URL template pointing to container release notes or changelog

Allowed values:Static URL or JS string template (${major}, ${minor}, ${patch}, ${prerelease}, ${original}, ${transformed}, ${image.name})

link.doc

Optionalstring

Link or URL template pointing to container or application documentation

Allowed values:Static URL or JS string template (${major}, ${minor}, ${patch}, ${prerelease}, ${original}, ${transformed}, ${image.name})

link.template

OptionalDeprecatedstring

Historical label pointing to container documentation (deprecated in favor of link.doc or link.changelog, maintained for backward compatibility)

Allowed values:Static URL or JS string template (${major}, ${minor}, ${patch}, ${prerelease}, ${original}, ${transformed}, ${image.name})

link.upstream

Optionalstring

Link or URL template pointing to upstream source code repository (GitHub, GitLab, etc.)

Allowed values:Static URL or JS string template (${major}, ${minor}, ${patch}, ${prerelease}, ${original}, ${transformed}, ${image.name})

stack

Optionalstring

Custom stack or project name for grouping (defaults to Compose project, K8s namespace, or Nomad namespace)

Allowed values:Any string

tag.exclude

Optionalregex

Regular expression matching image tags to ignore

Allowed values:Valid JavaScript RegExp (supports dynamic variables: ${major}, ${minor}, ${patch}, ${version}, ${flavor}, ${prerelease}, ${prefix}, ${raw}, ${original})

tag.include

Optionalregex

Regular expression matching image tags to consider as update candidates

Allowed values:Valid JavaScript RegExp (supports dynamic variables: ${major}, ${minor}, ${patch}, ${version}, ${flavor}, ${prerelease}, ${prefix}, ${raw}, ${original})

tag.transform

Optionalregex

Transform rule to extract clean semver versions from non-standard tags

Allowed values:`$regex => $string` with capturing groups

trigger.<type>.<name>.enabled

Optionalboolean

Enable or disable a specific trigger instance for this container (takes precedence over trigger type, include/exclude lists, and default settings)

Allowed values:Boolean (`true`, `false`)

trigger.<type>.enabled

Optionalboolean

Enable or disable all triggers of a specific provider type for this container (takes precedence over include/exclude lists and default settings)

Allowed values:Boolean (`true`, `false`)

trigger.exclude

Optionallist

List of triggers to exclude for this container

Allowed values:`trigger1,trigger2:threshold`

trigger.include

Optionallist

List of triggers to include for this container

Allowed values:`trigger1,trigger2:threshold`

watch

Optionalbooleandefault: true

Enable or disable monitoring for this container / workload

Allowed values:Boolean (`true`, `false`)

watch.delay

Optionalstring

Cool-down period before considering an update available for this container (can also be specified as tag.delay)

Allowed values:Duration string (e.g. `30s`, `10m`, `24h`, `3d`, `1w`)

watch.digest

Optionalbooleandefault: false

Track digest changes on registry for mutable tags (e.g. latest)

Allowed values:Boolean (`true`, `false`)

Practical Examples

1. Opt-in Monitoring (Monitor Only Selected Workloads)

When WATCHBYDEFAULT=false is configured on the watcher, workloads are ignored unless explicitly marked with watch=true:

Precedence Rules

For a detailed guide on how wud.watch takes precedence over watcher-level INCLUDE and EXCLUDE filters, see Container Filtering & Precedence Rules.

🐳 Docker
☸️ Kubernetes
🟢 Nomad
🐝 Docker Swarm

compose.yaml
services:
  mariadb:
    image: mariadb:10.4.5
    labels:
      - wud.watch=true

Docker CLI
docker run -d --name mariadb --label wud.watch=true mariadb:10.4.5

deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mariadb
  namespace: default
  annotations:
    getwud.app/watch: "true"
spec:
  replicas: 1
  template:
    spec:
      containers:
        - name: mariadb
          image: mariadb:10.4.5

job.nomad.hcl
job "mariadb" {
  meta {
    "getwud.app/watch" = "true"
  }
  group "db" {
    task "server" {
      driver = "docker"
      config {
        image = "mariadb:10.4.5"
      }
    }
  }
}

stack.yaml
version: '3.8'

services:
  mariadb:
    image: mariadb:10.4.5
    deploy:
      labels:
        - getwud.app/watch=true

2. Exclude Specific Workloads

When WATCHBYDEFAULT=true (the default), exclude specific workloads by setting watch=false:

🐳 Docker
☸️ Kubernetes
🟢 Nomad
🐝 Docker Swarm

compose.yaml
services:
  legacy_app:
    image: myapp:1.0.0
    labels:
      - wud.watch=false

deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: legacy-app
  annotations:
    getwud.app/watch: "false"
spec:
  template:
    spec:
      containers:
        - name: app
          image: myapp:1.0.0

job.nomad.hcl
job "legacy-app" {
  meta {
    "getwud.app/watch" = "false"
  }
  group "app" {
    task "server" {
      driver = "docker"
      config {
        image = "myapp:1.0.0"
      }
    }
  }
}

stack.yaml
version: '3.8'

services:
  legacy_app:
    image: myapp:1.0.0
    deploy:
      labels:
        - getwud.app/watch=false

3. Filter Tags with Regular Expressions

Filter which tags are considered valid candidates for updates by specifying inclusion or exclusion regex patterns.

For example, to monitor only standard x.y.z 3-part semver tags (ignoring alpine, beta, rc):

🐳 Docker
☸️ Kubernetes
🟢 Nomad
🐝 Docker Swarm

compose.yaml
services:
  mariadb:
    image: mariadb:10.4.5
    labels:
      - wud.tag.include=^\d+\.\d+\.\d+$

deployment.yaml
metadata:
  annotations:
    getwud.app/tag.include: "^\\d+\\.\\d+\\.\\d+$"

job.nomad.hcl
job "mariadb" {
  meta {
    "getwud.app/tag.include" = "^\\d+\\.\\d+\\.\\d+$"
  }
}

stack.yaml
version: '3.8'

services:
  mariadb:
    image: mariadb:10.4.5
    deploy:
      labels:
        - getwud.app/tag.include=^\d+\.\d+\.\d+$

Dynamic SemVer Variable Interpolation

When configuring tag.include or tag.exclude, you can dynamically interpolate variables based on the current container's image tag. This allows you to pin updates to the same major version, minor track, or OS flavor automatically without having to update the regex when bumping versions.

Supported Variables

Variable	Description	Example (for `v1.2.3-alpine3.20`)
`${major}`	Major version number	`1`
`${minor}`	Minor version number	`2`
`${patch}`	Patch version number	`3`
`${version}`	Full SemVer version (`${major}.${minor}.${patch}`)	`1.2.3`
`${flavor}`	Operating system or distribution flavor	`alpine3.20`
`${prerelease}`	Prerelease identifier (e.g. `rc.1`, `beta1`)	`""`
`${prefix}`	Tag prefix (e.g. `v`, `release-`)	`v`
`${raw}` / `${original}`	Original, untouched image tag value	`v1.2.3-alpine3.20`

Non-SemVer Image Tags

If the container's tag is not a valid SemVer (e.g. latest, stable) and a SemVer variable (${major}, ${minor}, ${patch}, ${version}) is referenced, WUD replaces the variable with (?!) (a negative lookahead that never matches any tag) and logs a warning. This safely prevents unwanted or uncontrolled updates on non-SemVer containers.

Docker Compose $$ Escaping

In Docker Compose files, Docker Compose uses $ for its own environment variable interpolation. To prevent Compose from evaluating WUD variables locally at startup, escape the dollar sign with a double dollar sign $$:

labels:
  - wud.tag.include=^$${major}\.$${minor}\.\d+$$

Recipes

🐳 Docker
☸️ Kubernetes
🟢 Nomad
🐝 Docker Swarm

compose.yaml
services:
  # 1. Pin to same minor version track (patch updates only)
  postgres:
    image: postgres:16.2-alpine3.20
    labels:
      - wud.tag.include=^$${major}\.$${minor}\.\d+-$${flavor}$$

  # 2. Pin to same major version track
  redis:
    image: redis:7.2.4-alpine
    labels:
      - wud.tag.include=^$${major}\.\d+\.\d+-$${flavor}$$

  # 3. Preserve tag prefix (e.g. v2.4.x)
  traefik:
    image: traefik:v2.10.7
    labels:
      - wud.tag.include=^$${prefix}$${major}\.$${minor}\.\d+$$

  # 4. Exclude current running tag
  app:
    image: myapp:1.2.3
    labels:
      - wud.tag.exclude=^$${raw}$$

deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgres
  annotations:
    # Pin to same minor track with flavor
    getwud.app/tag.include: "^${major}\\.${minor}\\.\\d+-${flavor}$"
spec:
  template:
    spec:
      containers:
        - name: postgres
          image: postgres:16.2-alpine3.20

job.nomad.hcl
job "postgres" {
  group "db" {
    task "server" {
      driver = "docker"
      config {
        image = "postgres:16.2-alpine3.20"
      }
      meta {
        # Pin to same minor track with flavor
        "getwud.app/tag.include" = "^${major}\\.${minor}\\.\\d+-${flavor}$"
      }
    }
  }
}

stack.yaml
version: '3.8'

services:
  postgres:
    image: postgres:16.2-alpine3.20
    deploy:
      labels:
        # Pin to same minor track with flavor
        - getwud.app/tag.include=^${major}\.${minor}\.\d+-${flavor}$

4. Transform Non-Standard Tags Before Semver Analysis

In certain cases, image tags include metadata suffixes (such as commit hashes or build numbers) like 1.0.0-99-7b368146.

By default, the trailing SHA-1 hash (-7b368146) interferes with comparison, even though 1.0.0-99 represents a valid semver version.

Syntax

$valid_regex_with_capturing_groups => $valid_string_with_placeholders

Capturing groups are referenced using $1, $2, etc.

🐳 Docker
☸️ Kubernetes
🟢 Nomad
🐝 Docker Swarm

compose.yaml
services:
  searx:
    image: searx/searx:1.0.0-269-7b368146
    labels:
      - wud.tag.include=^\d+\.\d+\.\d+-\d+-.*$
      - wud.tag.transform=^(\d+\.\d+\.\d+-\d+)-.*$ => $1

deployment.yaml
metadata:
  annotations:
    getwud.app/tag.include: "^\\d+\\.\\d+\\.\\d+-\\d+-.*$"
    getwud.app/tag.transform: "^(\\d+\\.\\d+\\.\\d+-\\d+)-.*$ => $1"

job.nomad.hcl
job "searx" {
  meta {
    "getwud.app/tag.include"   = "^\\d+\\.\\d+\\.\\d+-\\d+-.*$"
    "getwud.app/tag.transform" = "^(\\d+\\.\\d+\\.\\d+-\\d+)-.*$ => $1"
  }
}

stack.yaml
version: '3.8'

services:
  searx:
    image: searx/searx:1.0.0-269-7b368146
    deploy:
      labels:
        - getwud.app/tag.include=^\d+\.\d+\.\d+-\d+-.*$
        - getwud.app/tag.transform=^(\d+\.\d+\.\d+-\d+)-.*$ => $1

5. Enable Digest Watching

In addition to semver tag tracking, you can track whether the remote image digest for a mutable tag (such as latest, 10, or stable) has changed on the registry:

🐳 Docker
☸️ Kubernetes
🟢 Nomad
🐝 Docker Swarm

compose.yaml
services:
  redis:
    image: redis:alpine
    labels:
      - wud.watch.digest=true

deployment.yaml
metadata:
  annotations:
    getwud.app/watch.digest: "true"

job.nomad.hcl
job "redis" {
  meta {
    "getwud.app/watch.digest" = "true"
  }
}

stack.yaml
version: '3.8'

services:
  redis:
    image: redis:alpine
    deploy:
      labels:
        - getwud.app/watch.digest=true

6. Container Links & Rich Metadata (Changelog, Documentation, Upstream Source)

WUD provides dedicated labels to attach rich metadata links to your containers and workloads. These links appear as direct action buttons in the Web UI and are passed to all notification triggers (Discord, Telegram, Slack, Webhooks, etc.):

Documentation (link.doc): Link or URL template pointing to application documentation or guides.
Changelog (link.changelog): Link or URL template pointing to release notes or changelog entries.
Upstream Source (link.upstream): Link or URL template pointing to the upstream source code repository (e.g. GitHub, GitLab, Codeberg).

Dynamic Template Variables & Static URLs

All three labels (link.doc, link.changelog, and link.upstream), as well as the historical link.template, support static URLs or dynamic JavaScript string template variables evaluated against the container update data:

${major}: Major version number (e.g. 16)
${minor}: Minor version number (e.g. 2)
${patch}: Patch version number (e.g. 0)
${prerelease}: Prerelease identifier (e.g. beta.1)
${original}: The original unparsed tag value (e.g. 10.6.4-alpine)
${transformed}: The tag after applying tag.transform rules
${image.name}: Monitored container image name (e.g. mariadb or searx/searx)

Automatic Official Docker Hub Detection

For official Docker Hub images (e.g. postgres, redis, nginx, alpine or library/postgres), WUD automatically detects their official status (isOfficial = true).

When no custom documentation link is specified, WUD automatically sets documentationUrl to the official Docker Hub overview page (https://hub.docker.com/_/<image_name>).

Deprecation Notice: wud.link.template

The label wud.link.template (and its orchestrator aliases getwud.app/link.template) is deprecated in favor of wud.link.doc (for documentation) and wud.link.changelog (for version-specific release notes).

Migration Path:

If your template points to version changelogs or release notes, rename it to wud.link.changelog (or getwud.app/link.changelog).
If your template points to general documentation or upstream repositories, migrate to wud.link.doc or wud.link.upstream.

For backward compatibility, WUD will continue to respect link.template as a fallback for documentationUrl when link.doc is not defined.

Multi-Orchestrator Configuration

🐳 Docker
☸️ Kubernetes
🟢 Nomad
🐝 Docker Swarm

compose.yaml
services:
  mariadb:
    image: mariadb:10.6.4
    labels:
      - wud.link.doc=https://mariadb.org/documentation/
      - wud.link.changelog=https://mariadb.com/kb/en/mariadb-${major}${minor}${patch}-changelog
      - wud.link.upstream=https://github.com/MariaDB/server

deployment.yaml
metadata:
  annotations:
    getwud.app/link.doc: "https://mariadb.org/documentation/"
    getwud.app/link.changelog: "https://mariadb.com/kb/en/mariadb-${major}${minor}${patch}-changelog"
    getwud.app/link.upstream: "https://github.com/MariaDB/server"

job.nomad.hcl
job "mariadb" {
  meta {
    "getwud.app/link.doc"       = "https://mariadb.org/documentation/"
    "getwud.app/link.changelog" = "https://mariadb.com/kb/en/mariadb-${major}${minor}${patch}-changelog"
    "getwud.app/link.upstream"  = "https://github.com/MariaDB/server"
  }
}

stack.yaml
version: '3.8'

services:
  mariadb:
    image: mariadb:10.6.4
    deploy:
      labels:
        - getwud.app/link.doc=https://mariadb.org/documentation/
        - getwud.app/link.changelog=https://mariadb.com/kb/en/mariadb-${major}${minor}${patch}-changelog
        - getwud.app/link.upstream=https://github.com/MariaDB/server

7. Customize Display Name & Icon

Customize how workloads appear in the WUD Web UI and smart home integrations (e.g. Home Assistant):

Supported Icons

WUD supports the full Iconify catalog (over 150,000+ open-source icons across 150+ collections) using the standard collection:icon-name format, as well as arbitrary image URLs:

mdi: for Material Design Icons (mdi:database, mdi:docker)
simple-icons: (or si:) for Simple Icons (simple-icons:mysql, si:mariadb)
selfhst: (or sh:) for Selfh.st Icons (selfhst:authentik, selfhst:jellyfin)
logos: for SVG Logos (logos:redis, logos:postgresql)
fa6-solid:, fa6-regular:, fa6-brands: for Font Awesome (fa6-brands:github, fa:heart)
http:// or https:// for external image URLs (https://example.com/icon.png)
data:image/ for embedded base64/inline image data URIs (data:image/png;base64,...)

🐳 Docker
☸️ Kubernetes
🟢 Nomad
🐝 Docker Swarm

compose.yaml
services:
  mariadb:
    image: mariadb:10.6.4
    labels:
      - wud.display.name=Production MariaDB
      - wud.display.icon=si:mariadb

deployment.yaml
metadata:
  annotations:
    getwud.app/display.name: "Production MariaDB"
    getwud.app/display.icon: "si:mariadb"

job.nomad.hcl
job "mariadb" {
  meta {
    "getwud.app/display.name" = "Production MariaDB"
    "getwud.app/display.icon" = "si:mariadb"
  }
}

stack.yaml
version: '3.8'

services:
  mariadb:
    image: mariadb:10.6.4
    deploy:
      labels:
        - getwud.app/display.name=Production MariaDB
        - getwud.app/display.icon=si:mariadb

8. Assign Specific Triggers & Thresholds

Route notifications or auto-updates for a specific container to designated triggers:

Threshold Levels

all: Triggers on all updates (semver & digest).
major: Triggers on major, minor, or patch updates.
minor: Triggers only on minor or patch updates.
patch: Triggers only on patch updates.

🐳 Docker
☸️ Kubernetes
🟢 Nomad
🐝 Docker Swarm

compose.yaml
services:
  web_app:
    image: web_app:1.2.0
    labels:
      - wud.trigger.include=smtp.gmail,dockercompose.local:minor

deployment.yaml
metadata:
  annotations:
    getwud.app/trigger.include: "smtp.gmail,webhook.prod:minor"

job.nomad.hcl
job "web-app" {
  meta {
    "getwud.app/trigger.include" = "smtp.gmail,webhook.prod:minor"
  }
}

stack.yaml
version: '3.8'

services:
  web_app:
    image: web_app:1.2.0
    deploy:
      labels:
        - getwud.app/trigger.include=smtp.gmail,webhook.prod:minor

9. Configure Cool-Down Period Before Update Trigger

To prevent updating to fresh upstream releases immediately (e.g. to wait for hotfixes or community feedback), set a cool-down delay:

🐳 Docker
☸️ Kubernetes
🟢 Nomad
🐝 Docker Swarm

compose.yaml
services:
  web_app:
    image: web_app:1.2.0
    labels:
      - wud.watch.delay=3d

deployment.yaml
metadata:
  annotations:
    getwud.app/watch.delay: "3d"

job.nomad.hcl
job "web-app" {
  meta {
    "getwud.app/watch.delay" = "3d"
  }
}

stack.yaml
version: '3.8'

services:
  web_app:
    image: web_app:1.2.0
    deploy:
      labels:
        - getwud.app/watch.delay=3d

Multi-Container Targeting​

Available Properties​

Practical Examples​

1. Opt-in Monitoring (Monitor Only Selected Workloads)​

2. Exclude Specific Workloads​

3. Filter Tags with Regular Expressions​

Dynamic SemVer Variable Interpolation​

Supported Variables​

Recipes​

4. Transform Non-Standard Tags Before Semver Analysis​

Syntax​

5. Enable Digest Watching​

6. Container Links & Rich Metadata (Changelog, Documentation, Upstream Source)​

Dynamic Template Variables & Static URLs​

Automatic Official Docker Hub Detection​

Multi-Orchestrator Configuration​

7. Customize Display Name & Icon​

Supported Icons​

8. Assign Specific Triggers & Thresholds​

Threshold Levels​

9. Configure Cool-Down Period Before Update Trigger​

Multi-Container Targeting

Available Properties

Practical Examples

1. Opt-in Monitoring (Monitor Only Selected Workloads)

2. Exclude Specific Workloads

3. Filter Tags with Regular Expressions

Dynamic SemVer Variable Interpolation

Supported Variables

Recipes

4. Transform Non-Standard Tags Before Semver Analysis

Syntax

5. Enable Digest Watching

6. Container Links & Rich Metadata (Changelog, Documentation, Upstream Source)

Dynamic Template Variables & Static URLs

Automatic Official Docker Hub Detection

Multi-Orchestrator Configuration

7. Customize Display Name & Icon

Supported Icons

8. Assign Specific Triggers & Thresholds

Threshold Levels

9. Configure Cool-Down Period Before Update Trigger