Docker Watchers

The docker watcher lets you configure the Docker hosts you want to watch.

Variables

WATCHALL and WATCHBYDEFAULT are independent and operate at different stages. WATCHALL controls which container states Docker returns (running-only vs all states). WATCHBYDEFAULT controls whether unlabeled containers are watched — the dd.watch label always takes precedence when set. See the behavior matrix below for details.

Notes:

• If no watcher is configured, a default one named local will be automatically created (reading the Docker socket). To suppress this default watcher (e.g. when running as a controller-only node for remote agents), set DD_LOCAL_WATCHER=false.
• Multiple watchers can be configured (if you have multiple Docker hosts to watch). Give them different names.
• Socket configuration and host/port configuration are mutually exclusive.
• When MAINTENANCE_WINDOW is configured and a check is skipped outside the allowed schedule, drydock queues one pending check and runs it automatically when the next maintenance window opens.
• wud.* labels are ignored as of v1.6. To rewrite old compose files, run node dist/index.js config migrate --dry-run then node dist/index.js config migrate --file <path>.
• If watcher logger initialization fails, drydock automatically falls back to structured stderr JSON logs and increments dd_watcher_logger_init_failures_total{type,name}. Alert on non-zero increases to catch degraded logging early.
• The watcher fan-out is capped at 10 concurrent watchContainer invocations per cron cycle. On inventories with 40–200 containers this prevents a burst of simultaneous registry calls that would trigger rate limits despite the token bucket.
• Hybrid image:tag@sha256:digest references (e.g. docker.io/valkey/valkey:9@sha256:bcf6…) are handled correctly: drydock preserves both the tag and the digest rather than falling back to digest-only mode, so the human-readable tag is displayed in the UI and the registry router resolves the provider cleanly.
• Label-derived watcher fields (tagFamily, tagPinInfo, includeTags, excludeTags, transformTags, triggerInclude, triggerExclude) are re-derived on Docker update events (e.g. after docker compose up -d). Labels set on the recreated container take effect immediately without waiting for the next cron cycle; removing a tag-policy label restores its imgset/watcher default.
• Floating semver aliases (e.g. 3.3 and 3.3.0, which both coerce to the same semver) are excluded from the greater-than check in candidate ranking, so aliases that resolve identically are never reported as upgrades.
• Fully-pinned specific tags (3+ numeric segments, e.g. 1.4.5, v1.13.3) also compare by digest by default, the same as floating tags, so a rebuilt image republished under the same tag is detected. Version climbing across tags for a pinned image is opt-in via dd.tag.include, dd.tag.family=loose, or the actionable watcher default DD_WATCHER_{watcher_name}_TAG_FAMILY=loose. The watcher-wide loose setting can make cross-version candidates actionable and therefore eligible for configured action triggers; use it deliberately. Drydock separately computes an informational updateInsight — the best newer same-family tag available in the registry — which never triggers an update or notification and never changes updateAvailable/updateKind. The UI renders that insight as a neutral Pinned state with a grey current tag → blue newer tag and a Major/Minor/Patch chip; hover text supplies additional detail. Control the informational channel with dd.tag.pin.info, matching-imgset TAG_PIN_INFO, or the watcher default TAG_PIN_INFO.
• A Major insight is not automatically a mismatch: strict family matching preserves prefix, suffix/variant shape, numeric precision, and CalVer rules, but it does not impose a same-major ceiling. By contrast, a Major result shown as an actionable update means an actionable policy such as dd.tag.family=loose or dd.tag.include is in effect. The Immich v3.0.2 Major report in #498 was caused by dd.tag.family=loose on only the machine-learning container. Loose mode still preserves suffix variants — for example, v2.7.5-openvino can climb to v3.0.2-openvino, never bare v3.0.2 — and that historical cross-suffix bug is regression-covered.

Variable examples

Watch the local docker host every day at 1am

services:
  drydock:
    image: codeswhat/drydock
    ...
    environment:
        - DD_WATCHER_LOCAL_CRON=0 1 * * *

docker run \
    -e DD_WATCHER_LOCAL_CRON="0 1 * * *" \
  ...
  codeswhat/drydock

Watch all containers regardless of their status (created, paused, exited, restarting, running...)

services:
  drydock:
    image: codeswhat/drydock
    ...
    environment:
        - DD_WATCHER_LOCAL_WATCHALL=true

docker run \
    -e DD_WATCHER_LOCAL_WATCHALL="true" \
  ...
  codeswhat/drydock

WATCHALL / WATCHBYDEFAULT behavior matrix

These two variables are orthogonal — they filter at different stages of the container selection pipeline:

1. WATCHALL (Docker API level) — decides which container states are fetched from Docker.
2. WATCHBYDEFAULT (per-container level) — decides whether containers without a dd.watch label are watched. An explicit dd.watch label always takes precedence.

Watch a remote docker host via TCP on 2375

services:
  drydock:
    image: codeswhat/drydock
    ...
    environment:
        - DD_WATCHER_MYREMOTEHOST_HOST=myremotehost

docker run \
    -e DD_WATCHER_MYREMOTEHOST_HOST="myremotehost" \
  ...
  codeswhat/drydock

Watch a remote docker host behind HTTPS with bearer auth

services:
  drydock:
    image: codeswhat/drydock
    ...
    environment:
        - DD_WATCHER_MYREMOTEHOST_HOST=myremotehost
        - DD_WATCHER_MYREMOTEHOST_PORT=443
        - DD_WATCHER_MYREMOTEHOST_PROTOCOL=https
        - DD_WATCHER_MYREMOTEHOST_AUTH_TYPE=BEARER
        - DD_WATCHER_MYREMOTEHOST_AUTH_BEARER=my-secret-token

docker run \
    -e DD_WATCHER_MYREMOTEHOST_HOST="myremotehost" \
    -e DD_WATCHER_MYREMOTEHOST_PORT="443" \
    -e DD_WATCHER_MYREMOTEHOST_PROTOCOL="https" \
    -e DD_WATCHER_MYREMOTEHOST_AUTH_TYPE="BEARER" \
    -e DD_WATCHER_MYREMOTEHOST_AUTH_BEARER="my-secret-token" \
  ...
  codeswhat/drydock

Watch a remote docker host via TCP with TLS enabled on 2376

services:
  drydock:
    image: codeswhat/drydock
    ...
    environment:
        - DD_WATCHER_MYREMOTEHOST_HOST=myremotehost
        - DD_WATCHER_MYREMOTEHOST_PORT=2376
        - DD_WATCHER_MYREMOTEHOST_CAFILE=/certs/ca.pem
        - DD_WATCHER_MYREMOTEHOST_CERTFILE=/certs/cert.pem
        - DD_WATCHER_MYREMOTEHOST_KEYFILE=/certs/key.pem
    volumes:
        - /my-host/my-certs/ca.pem:/certs/ca.pem:ro
        - /my-host/my-certs/cert.pem:/certs/cert.pem:ro
        - /my-host/my-certs/key.pem:/certs/key.pem:ro

docker run \
    -e DD_WATCHER_MYREMOTEHOST_HOST="myremotehost" \
    -e DD_WATCHER_MYREMOTEHOST_PORT="2376" \
    -e DD_WATCHER_MYREMOTEHOST_CAFILE="/certs/ca.pem" \
    -e DD_WATCHER_MYREMOTEHOST_CERTFILE="/certs/cert.pem" \
    -e DD_WATCHER_MYREMOTEHOST_KEYFILE="/certs/key.pem" \
    -v /my-host/my-certs/ca.pem:/certs/ca.pem:ro \
    -v /my-host/my-certs/cert.pem:/certs/cert.pem:ro \
    -v /my-host/my-certs/key.pem:/certs/key.pem:ro \
  ...
  codeswhat/drydock

Connecting via SSH

Drydock does not currently support the ssh:// protocol for remote Docker connections. The PROTOCOL variable only accepts http or https.

If your remote Docker host is only reachable over SSH, you can use an SSH tunnel to forward the remote Docker socket to a local TCP port or Unix socket, then point Drydock at that forwarded endpoint:

# Forward the remote Docker socket to a local TCP port
ssh -nNT -L 2375:/var/run/docker.sock user@remote-host

Then configure Drydock to connect to the forwarded port:

services:
  drydock:
    image: codeswhat/drydock
    ...
    environment:
      - DD_WATCHER_MYREMOTEHOST_HOST=host.docker.internal
      - DD_WATCHER_MYREMOTEHOST_PORT=2375
    extra_hosts:
      - "host.docker.internal:host-gateway"

Docker Socket Security

Drydock needs to communicate with the Docker Engine API to monitor containers and (optionally) perform updates. By default this means mounting the Docker socket — which grants broad access to the host. This section covers all available approaches to secure that access, from the recommended socket proxy to remote TLS connections.

Security comparison

Option 1: Socket proxy (recommended)

A socket proxy runs as a separate container with access to the Docker socket and exposes only the API endpoints Drydock needs. Drydock connects to the proxy over HTTP, so no socket mount is required at all.

This is the recommended approach for all deployments. It provides a strict security boundary with minimal setup.

services:
  drydock:
    image: codeswhat/drydock
    depends_on:
      socket-proxy:
        condition: service_healthy
    environment:
      - DD_WATCHER_LOCAL_HOST=socket-proxy
      - DD_WATCHER_LOCAL_PORT=2375
    ports:
      - 3000:3000

  socket-proxy:
    image: tecnativa/docker-socket-proxy
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - CONTAINERS=1
      - IMAGES=1
      - EVENTS=1
      - SERVICES=1
      - INFO=1       # required for daemon hostname detection (notification identity)
    healthcheck:
      test: wget --spider http://localhost:2375/version || exit 1
      interval: 5s
      timeout: 3s
      retries: 3
      start_period: 5s
    restart: unless-stopped

The :ro (read-only) flag on the Docker socket mount is omitted intentionally. The proxy's environment variables (CONTAINERS, EVENTS, etc.) control which API endpoints are exposed — that is the actual security boundary. The :ro flag on Unix sockets does not prevent API communication and can cause connection failures on some Linux kernels.

Proxy permissions by feature

Alternative socket proxies

Tecnativa/docker-socket-proxy is the most widely used option, but any HAProxy or nginx-based Docker socket proxy that filters by HTTP method and path will work. The key requirement is that the proxy exposes the Docker Engine API endpoints listed in the permissions table above and blocks everything else (especially exec, build, and swarm endpoints).

Other compatible proxies include linuxserver/docker-socket-proxy (a fork with additional features).

Option 2: Remote Docker over TLS

Instead of mounting the socket at all, Drydock can connect to a remote Docker host over the network using mutual TLS (mTLS). This is ideal when you need a single Drydock instance to reach a remote Docker daemon directly, or want to avoid socket mounts entirely. For monitoring containers across multiple independent hosts from one UI, consider Agents, which don't require exposing the Docker API over the network.

Step 1: Generate TLS certificates on the Docker host

Follow the official Docker TLS guide to generate a CA, server certificate, and client certificate.

Step 2: Configure the Docker daemon

Configure the daemon to listen on a TLS port by adding this to /etc/docker/daemon.json:

{
  "hosts": ["unix:///var/run/docker.sock", "tcp://0.0.0.0:2376"],
  "tls": true,
  "tlscacert": "/etc/docker/ca.pem",
  "tlscert": "/etc/docker/server-cert.pem",
  "tlskey": "/etc/docker/server-key.pem",
  "tlsverify": true
}

Step 3: Configure Drydock

Configure Drydock with the client certificates:

services:
  drydock:
    image: codeswhat/drydock
    environment:
      - DD_WATCHER_REMOTE_HOST=docker-host.example.com
      - DD_WATCHER_REMOTE_PORT=2376
      - DD_WATCHER_REMOTE_CAFILE=/certs/ca.pem
      - DD_WATCHER_REMOTE_CERTFILE=/certs/client-cert.pem
      - DD_WATCHER_REMOTE_KEYFILE=/certs/client-key.pem
    volumes:
      - ./certs/ca.pem:/certs/ca.pem:ro
      - ./certs/client-cert.pem:/certs/client-cert.pem:ro
      - ./certs/client-key.pem:/certs/client-key.pem:ro
    ports:
      - 3000:3000

When TLS certificates are provided (CAFILE, CERTFILE, KEYFILE), Drydock automatically uses HTTPS regardless of the PROTOCOL setting.

Option 3: Rootless Docker

Rootless Docker runs the Docker daemon entirely in user space without root privileges. Even full socket access does not grant host root because the daemon itself is unprivileged.

Step 1: Install rootless Docker following the official guide.

Step 2: Find your rootless socket path:

echo $XDG_RUNTIME_DIR/docker.sock
# Typically: /run/user/1000/docker.sock

Step 3: Mount the rootless socket:

services:
  drydock:
    image: codeswhat/drydock
    volumes:
      - /run/user/1000/docker.sock:/var/run/docker.sock
    ports:
      - 3000:3000

The rootless socket path varies by user. Replace 1000 with your user's UID (id -u).

You can combine rootless Docker with a socket proxy for defense in depth — even if the proxy is compromised, the attacker only gains unprivileged access.

Option 4: Direct socket mount (default)

The simplest approach — mount the Docker socket directly. Drydock runs as a non-root user inside the container, but the socket grants access to the full Docker API.

services:
  drydock:
    image: codeswhat/drydock
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - 3000:3000

Option 5: Break-glass root mode (least secure)

If the non-root user cannot connect to the socket (common with :ro mounts), you can explicitly opt into root mode. This is a break-glass path and should not be your default. Both flags are required; setting only DD_RUN_AS_ROOT=true fails closed at startup.

services:
  drydock:
    image: codeswhat/drydock
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - DD_RUN_AS_ROOT=true
      - DD_ALLOW_INSECURE_ROOT=true
    ports:
      - 3000:3000

Which Docker API endpoints does Drydock use?

Understanding exactly what Drydock accesses helps you configure socket proxies and evaluate your security posture.

Read-only operations (watchers):

Write operations (triggers — only when performing updates):

If you only need monitoring (no auto-updates), a read-only socket proxy configuration is sufficient.

Podman Quick Start

Podman works with Drydock through Podman's Docker-compatible API socket.

Socket path mapping (podman.sock vs docker.sock)

Use Podman's host socket path, but mount it inside the Drydock container at /var/run/docker.sock so existing Drydock defaults still work.

Rootful vs rootless setup

• Rootful Podman socket: sudo systemctl enable --now podman.socket
• Rootless Podman socket: systemctl --user enable --now podman.socket

services:
  drydock:
    image: codeswhat/drydock
    volumes:
      - /run/podman/podman.sock:/var/run/docker.sock
    environment:
      - DD_WATCHER_LOCAL_SOCKET=/var/run/docker.sock
      - DD_ACTION_DOCKER_LOCAL_AUTO=false
    ports:
      - 3000:3000

services:
  drydock:
    image: codeswhat/drydock
    volumes:
      - ${XDG_RUNTIME_DIR}/podman/podman.sock:/var/run/docker.sock
    environment:
      - DD_WATCHER_LOCAL_SOCKET=/var/run/docker.sock
      - DD_ACTION_DOCKER_LOCAL_AUTO=false
    ports:
      - 3000:3000

services:
  drydock:
    image: codeswhat/drydock
    depends_on:
      socket-proxy:
        condition: service_healthy
    environment:
      - DD_WATCHER_LOCAL_HOST=socket-proxy
      - DD_WATCHER_LOCAL_PORT=2375
      - DD_ACTION_DOCKER_LOCAL_AUTO=false
    ports:
      - 3000:3000

  socket-proxy:
    image: tecnativa/docker-socket-proxy
    environment:
      - SOCKET_PATH=/run/podman/podman.sock
      - CONTAINERS=1
      - IMAGES=1
      - EVENTS=1
      - SERVICES=1
      - INFO=1       # required for daemon hostname detection (notification identity)
      - POST=1
      - NETWORKS=1
    volumes:
      - /run/podman/podman.sock:/run/podman/podman.sock
    healthcheck:
      test: wget --spider http://localhost:2375/version || exit 1
      interval: 5s
      timeout: 3s
      retries: 3
      start_period: 5s

Known limitations and tested versions

For common Podman troubleshooting, see FAQ Podman entries.

Watch 1 local Docker host and 2 remote docker hosts at the same time

services:
  drydock:
    image: codeswhat/drydock
    ...
    environment:
        -  DD_WATCHER_LOCAL_SOCKET=/var/run/docker.sock
        -  DD_WATCHER_MYREMOTEHOST1_HOST=myremotehost1
        -  DD_WATCHER_MYREMOTEHOST2_HOST=myremotehost2

docker run \
    -e  DD_WATCHER_LOCAL_SOCKET="/var/run/docker.sock" \
    -e  DD_WATCHER_MYREMOTEHOST1_HOST="myremotehost1" \
    -e  DD_WATCHER_MYREMOTEHOST2_HOST="myremotehost2" \
  ...
  codeswhat/drydock

Maintenance window

Only allow update checks between 2 AM and 4 AM in Europe/Berlin:

services:
  drydock:
    image: codeswhat/drydock
    ...
    environment:
      - DD_WATCHER_LOCAL_CRON=0 * * * *
      - DD_WATCHER_LOCAL_MAINTENANCE_WINDOW=0 2-3 * * *
      - DD_WATCHER_LOCAL_MAINTENANCE_WINDOW_TZ=Europe/Berlin

docker run \
    -e DD_WATCHER_LOCAL_CRON="0 * * * *" \
    -e DD_WATCHER_LOCAL_MAINTENANCE_WINDOW="0 2-3 * * *" \
    -e DD_WATCHER_LOCAL_MAINTENANCE_WINDOW_TZ="Europe/Berlin" \
  ...
  codeswhat/drydock

Image Set Presets

Use IMGSET to define reusable defaults by image reference. This is useful when many containers need the same tag filters, link template, icon, or trigger routing.

Looking for ready-to-copy presets for common containers? See Popular IMGSET Presets.

Supported imgset keys

• DD_WATCHER_{watcher_name}_IMGSET_{imgset_name}_IMAGE
• DD_WATCHER_{watcher_name}_IMGSET_{imgset_name}_TAG_INCLUDE
• DD_WATCHER_{watcher_name}_IMGSET_{imgset_name}_TAG_EXCLUDE
• DD_WATCHER_{watcher_name}_IMGSET_{imgset_name}_TAG_TRANSFORM
• DD_WATCHER_{watcher_name}_IMGSET_{imgset_name}_LINK_TEMPLATE
• DD_WATCHER_{watcher_name}_IMGSET_{imgset_name}_DISPLAY_NAME
• DD_WATCHER_{watcher_name}_IMGSET_{imgset_name}_DISPLAY_ICON
• DD_WATCHER_{watcher_name}_IMGSET_{imgset_name}_TRIGGER_INCLUDE
• DD_WATCHER_{watcher_name}_IMGSET_{imgset_name}_TAG_FAMILY
• DD_WATCHER_{watcher_name}_IMGSET_{imgset_name}_TAG_PIN_INFO
• DD_WATCHER_{watcher_name}_IMGSET_{imgset_name}_WATCH_DIGEST
• DD_WATCHER_{watcher_name}_IMGSET_{imgset_name}_INSPECT_TAG_PATH
• DD_WATCHER_{watcher_name}_IMGSET_{imgset_name}_TRIGGER_EXCLUDE
• DD_WATCHER_{watcher_name}_IMGSET_{imgset_name}_REGISTRY_LOOKUP_IMAGE
• DD_WATCHER_{watcher_name}_IMGSET_{imgset_name}_REGISTRY_LOOKUP_URL
• DD_WATCHER_{watcher_name}_IMGSET_{imgset_name}_INCLUDE
• DD_WATCHER_{watcher_name}_IMGSET_{imgset_name}_EXCLUDE
• DD_WATCHER_{watcher_name}_IMGSET_{imgset_name}_TRANSFORM

INCLUDE/EXCLUDE/TRANSFORM are shorthand aliases for TAG_INCLUDE/TAG_EXCLUDE/TAG_TRANSFORM — prefer the TAG_ form since it matches the dd.tag.* label naming used everywhere else. REGISTRY_LOOKUP_URL is an alias for REGISTRY_LOOKUP_IMAGE.

Imgset precedence

• dd.* labels on the container (or swarm service/container merged labels) are highest priority.
• Matching IMGSET values apply when the corresponding label is not set.
• Watcher-level TAG_FAMILY and TAG_PIN_INFO values apply when neither a label nor imgset sets that policy.
• Built-in defaults are strict for tag family and true for pin insight.

Imgset example

services:
  drydock:
    image: codeswhat/drydock
    environment:
      - DD_WATCHER_LOCAL_IMGSET_HOMEASSISTANT_IMAGE=ghcr.io/home-assistant/home-assistant
      - DD_WATCHER_LOCAL_IMGSET_HOMEASSISTANT_TAG_INCLUDE=^\\d+\\.\\d+\\.\\d+$$
      - DD_WATCHER_LOCAL_IMGSET_HOMEASSISTANT_DISPLAY_NAME=Home Assistant
      - DD_WATCHER_LOCAL_IMGSET_HOMEASSISTANT_DISPLAY_ICON=hl-home-assistant
      - DD_WATCHER_LOCAL_IMGSET_HOMEASSISTANT_LINK_TEMPLATE=https://www.home-assistant.io/changelogs/core-$${major}$${minor}$${patch}
      - DD_WATCHER_LOCAL_IMGSET_HOMEASSISTANT_TRIGGER_INCLUDE=ntfy.default:major

Labels

To fine-tune the behaviour of drydock per container, you can add labels on them.

dd.runtime.entrypoint.origin and dd.runtime.cmd.origin are managed automatically by the Docker trigger during container updates. You only need to set them manually if drydock cannot detect the origin (shows unknown) and you want to explicitly pin or release a custom entrypoint/cmd.

Update-policy precedence

Each field resolves independently. A missing value falls through to the next tier; skip lists replace the lower-tier list rather than being concatenated.

UI/API overrides persist across Drydock restarts, container recreation, and later label changes. Removing a label does not silently remove an override. The policy editor shows an Overridden badge when an override materially differs from the declarative value; Revert clears the selected override and immediately reveals the current label, watcher, or built-in value. Empty skip-list overrides are intentional: Clear Skips can suppress a declarative skip list without deleting the declaration, while Revert restores it.

Label examples

Include specific containers to watch

Set WATCHBYDEFAULT=false so that only containers with an explicit dd.watch=true label are monitored.

services:
  drydock:
    image: codeswhat/drydock
    ...
    environment:
      - DD_WATCHER_LOCAL_WATCHBYDEFAULT=false

docker run \
    -e DD_WATCHER_LOCAL_WATCHBYDEFAULT="false" \
  ...
  codeswhat/drydock

Then add the dd.watch=true label on the containers you want to watch.

services:
  mariadb:
    image: mariadb:10.4.5
    ...
    labels:
      - dd.watch=true

docker run -d --name mariadb --label dd.watch=true mariadb:10.4.5

Exclude specific containers to watch

Ensure DD_WATCHER_{watcher_name}_WATCHBYDEFAULT is true (default value).

Then add the dd.watch=false label on the containers you want to exclude from being watched.

services:
  mariadb:
    image: mariadb:10.4.5
    ...
    labels:
      - dd.watch=false

docker run -d --name mariadb --label dd.watch=false mariadb:10.4.5

Derive a semver from Docker inspect when image tag is latest

Use this when the running container exposes a version label in docker inspect.

services:
  myapp:
    image: ghcr.io/example/myapp:latest
    labels:
      - dd.inspect.tag.path=Config/Labels/org.opencontainers.image.version

docker run -d \
  --name myapp \
  --label dd.inspect.tag.path=Config/Labels/org.opencontainers.image.version \
  ghcr.io/example/myapp:latest

Show the app version from inspect without changing update detection

Use dd.inspect.tag.version-only=true when the inspect path value is a display-only version string that would break update detection if used as the image tag (for example when the registry tag and the embedded app version differ in format).

services:
  myapp:
    image: ghcr.io/example/myapp:latest
    labels:
      - dd.inspect.tag.path=Config/Labels/org.opencontainers.image.version
      - dd.inspect.tag.version-only=true

docker run -d \
  --name myapp \
  --label dd.inspect.tag.path=Config/Labels/org.opencontainers.image.version \
  --label dd.inspect.tag.version-only=true \
  ghcr.io/example/myapp:latest

Use an alternative image for update lookups

Use this when your runtime image is pulled from a cache/proxy registry, but you want updates checked against an upstream image.

services:
  traefik:
    image: harbor.example.com/dockerhub-proxy/traefik:v3.5.3
    labels:
      - dd.watch=true
      - dd.registry.lookup.image=library/traefik

docker run -d \
  --name traefik \
  --label 'dd.watch=true' \
  --label 'dd.registry.lookup.image=library/traefik' \
  harbor.example.com/dockerhub-proxy/traefik:v3.5.3

Include only 3 digits semver tags

You can filter (by inclusion or exclusion) which versions can be candidates for update.

For example, you can indicate that you want to watch x.y.z versions only

services:

  mariadb:
    image: mariadb:10.4.5
    labels:
      - dd.tag.include=^\d+\.\d+\.\d+$$

docker run -d --name mariadb --label 'dd.tag.include=^\d+\.\d+\.\d+$' mariadb:10.4.5

Transform the tags before performing the analysis

In certain cases, tag values are so badly formatted that the resolution algorithm cannot find any valid update candidates or, worst, find bad positive matches.

For example, you can encounter such an issue if you need to deal with tags looking like 1.0.0-99-7b368146, 1.0.0-273-21d7efa6...
By default, drydock will report bad positive matches because of the sha-1 part at the end of the tag value (-7b368146...).
That's a shame because 1.0.0-99 and 1.0.0-273 would have been valid semver values ($major.$minor.$patch-$prerelease).

You can get around this issue by providing a function that keeps only the part you are interested in.

How does it work?
The transform function must follow the following syntax:

$valid_regex_with_capturing_groups => $valid_string_with_placeholders

For example:

^(\d+\.\d+\.\d+-\d+)-.*$ => $1

The capturing groups are accessible with the syntax $1, $2, $3....

For example, to watch only x.y.z-n-hash-style tags and strip the hash suffix before comparison:

services:

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

docker run -d --name searx \
--label 'dd.tag.include=^\d+\.\d+\.\d+-\d+-.*$' \
--label 'dd.tag.transform=^(\d+\.\d+\.\d+-\d+)-.*$ => $1' \
searx/searx:1.0.0-269-7b368146

Enable digest watching

In addition to semver tag tracking, drydock can track whether the digest associated with the local tag has been updated. This is enabled automatically for floating tags known to move in place (latest, stable, 10, 10.6, 16-alpine). Add dd.watch.digest=true when you want to force digest tracking for a specific container, or dd.watch.digest=false when you want to opt a high-churn Docker Hub image out.

services:

  mariadb:
    image: mariadb:10
    labels:
      - dd.tag.include=^\d+$$
      - dd.watch.digest=true

docker run -d --name mariadb --label 'dd.tag.include=^\d+$' --label dd.watch.digest=true mariadb:10

Associate a link to the container version

You can associate a browsable link to the container version using a templated string. For example, if you want to associate a mariadb version to a changelog (e.g. https://mariadb.com/kb/en/mariadb-1064-changelog),

you would specify a template like https://mariadb.com/kb/en/mariadb-${major}${minor}${patch}-changelog

The available variables are:

• ${original} the original unparsed tag
• ${transformed} the original unparsed tag transformed with the optional dd.tag.transform label option
• ${major} the major version (if tag value is semver)
• ${minor} the minor version (if tag value is semver)
• ${patch} the patch version (if tag value is semver)
• ${prerelease} the prerelease version (if tag value is semver)

services:

  mariadb:
    image: mariadb:10.6.4
    labels:
      - dd.link.template=https://mariadb.com/kb/en/mariadb-$${major}$${minor}$${patch}-changelog

docker run -d --name mariadb --label 'dd.link.template=https://mariadb.com/kb/en/mariadb-${major}${minor}${patch}-changelog' mariadb:10

Customize the name and the icon to display

You can customize the name & the icon of a container (displayed in the UI, in Home-Assistant...)

Icons must be prefixed with:

• fab: or fab- for Fontawesome brand icons (fab:github, fab-mailchimp...)
• far: or far- for Fontawesome regular icons (far:heart, far-house...)
• fas: or fas- for Fontawesome solid icons (fas:heart, fas-house...)
• hl: or hl- for Homarr Labs icons (hl:plex, hl-authelia...)
• mdi: or mdi- icons are auto-resolved to Dashboard Icons but are not recommended; prefer hl: or fa prefixes instead
• sh: or sh- for Selfh.st (sh:authentik, sh-authelia-light...) (only works for logo available as png)
• si: or si- for Simple icons (si:mysql, si-plex...)

services:

  mariadb:
    image: mariadb:10.6.4
    labels:
      - dd.display.name=Maria DB
      - dd.display.icon=si:mariadb

docker run -d --name mariadb --label 'dd.display.name=Maria DB' --label 'dd.display.icon=si:mariadb' mariadb:10.6.4

Assign different triggers to containers

You can assign different triggers and thresholds on a per container basis.

Example send a mail notification for all updates but auto-update only if minor or patch

services:

  my_important_service:
    image: my_important_service:1.0.0
    labels:
      - dd.notification.include=smtp.gmail
      - dd.action.include=dockercompose.local:minor

docker run -d --name my_important_service --label 'dd.notification.include=smtp.gmail' --label 'dd.action.include=dockercompose.local:minor' my_important_service:1.0.0

• dd.notification.include=smtp.gmail is a shorthand for dd.notification.include=smtp.gmail:all
• dd.action.include=update (or dd.action.exclude=update) targets all triggers named update, for example docker.update and dockercompose.update

Threshold values:

Container Runtime Details

Each monitored container exposes runtime details sourced from Docker inspect and the container summary. These are visible in the API response and the UI:

Container Status Fields

The container model includes additional fields useful for understanding update state:

Next-run visibility

The Watchers and Agents views show when each watcher will next poll. The Next Run column displays a live relative countdown (e.g. "in 14m"). Hover over the countdown to see the absolute local timestamp (e.g. Apr 18, 14:32:07), making it easy to correlate the next poll with other scheduled work. The watcher API also exposes nextRunAt for programmatic consumers.

UI: floating-tag detection and Hide Pinned

Floating tag detection (tagPrecision)

drydock classifies each container's tag as specific (pinned release, e.g. 1.4.5) or floating (mutable alias, e.g. latest, v3, 16-alpine) using the tagPrecision classifier. This has two practical effects:

1. Auto-digest watching — Floating tags on non-Docker Hub registries have digest watching enabled automatically so in-place rebuilds are detected even when the tag name does not change.
2. Caution badge — When a container has a floating tag without digest watching active, the container detail view shows a caution indicator.

The tagPrecision field is computed from the tag name and any active dd.tag.transform. You do not need to configure it manually.

Tag and Version columns

The containers table has two distinct columns for version information:

• Tag (column key version) — the image tag used for update detection (e.g. latest, 1.4.5). This column was called "Version" in releases before v1.5.1; the column key is unchanged so saved column preferences keep working.
• Version (column key softwareVersion) — the application version surfaced from image.softwareVersion (the org.opencontainers.image.version OCI label, a dd.inspect.tag.path extract, or other runtime metadata). Falls back to the image tag when softwareVersion is not available. Visible by default for new installs; added automatically to saved column lists on upgrade.

Version column display

The Tag column adapts based on tagPrecision:

• Floating-tag + digest-watch containers (e.g. prom/prometheus:latest): shows the human-readable tag (not raw SHA). The digest transition is available in the cell tooltip and detail panels.
• Digest-pinned containers (image.tag.value starts with sha256:): shows the sha256:abc… → sha256:def… pair directly in the cell.

Hide Pinned toggle

The Hide Pinned filter in the Containers toolbar hides containers whose tagPrecision is specific. This is useful for decluttering the list when you have infrastructure containers (databases, proxies) pinned to specific versions and want to focus on containers with available updates. The preference is persisted across sessions.

Docker Event Stream

The watcher monitors Docker events (container create, destroy, start, stop, etc.) in real time. If the event stream disconnects, Drydock automatically reconnects with exponential backoff starting at 1 second and capping at 30 seconds.

When using third-party socket proxies, periodic reconnects are expected: many proxies close idle long-lived HTTP connections after their configured timeout. In logs this appears as:

Docker event stream error (aborted); reconnect attempt #1 in 1000ms

followed by:

Listening to docker events

The first reconnect attempt is logged at info level since it is expected behavior (proxy timeout or network blip). If the first attempt fails and subsequent reconnects are needed, those are logged at warn level to flag a potential real problem.

Event gap during reconnect

Container lifecycle events (create, start, stop, destroy) that occur during the brief reconnect window are not captured until the next scheduled poll cycle. The reconnect window is typically ~1 second under normal conditions. In practice this is rarely noticeable because the next cron poll will pick up the current container state, but it means Drydock does not guarantee zero missed events across a reconnect.

A future release will wire the reconnect path to request events from the last-seen timestamp, closing this gap entirely.

Native socket proxy

The root cause of proxy-timeout reconnects is that Drydock cannot control idle timeout behavior on third-party proxies. A purpose-built Drydock socket proxy is on the roadmap.

Reduce proxy-timeout reconnect churn

Until the native proxy ships, you can reduce reconnect noise:

1. Increase your proxy idle timeout (for example, linuxserver socket-proxy TIMEOUT=86400s).
2. Prefer direct socket mount when your environment allows it.
3. If your proxy supports endpoint-specific behavior, exempt Docker /events streams from idle timeout.
4. As a workaround, run a lightweight heartbeat container (e.g. alpine:latest with command: sh -c "sleep 300" and restart: always) to keep the proxy connection path active.