Docker Watchers

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

Edit a watcher schedule in the UI

This editor is new in v1.8.0-rc.1 builds and requires a writable configuration file.

Open Watchers, select a watcher, then choose Edit schedule in its detail panel. This editor changes four settings for existing controller-local watchers: cron, maintenancewindow, maintenancewindowtz, and maintenancewindowscope. It requires a mounted configuration file and an authorized session. Agent watchers, environment-owned values and referenced values are read-only. The panel shows whether each field comes from the file, environment, a reference or a default. An unavailable API or file disables editing; the UI does not create a configuration file.

Save sends only changed fields through PATCH /api/v1/config/editor/watchers. Remove file value / use default explicitly removes that setting from YAML. For the optional maintenance window, removal leaves no window configured. An empty text value is instead submitted as a value and checked by the server's startup Joi validation. Cancel or closing the panel before Save sends no write. There is no autosave or background snapshot polling.

The editor loads a revision with its snapshot. A stale revision or a field that has become read-only produces a conflict, retains the draft and disables Save. Use Discard draft and reload to explicitly replace the draft with a fresh snapshot. The UI never retries a save with a newer revision automatically. After saving, it distinguishes a file saved and applied live from a saved file whose reload or audit reported problems. Reload counts, errors, restart fields and orphaned notification-rule references are shown when reported. An uncertain network outcome requires reloading before another change.

Untouched credentials, _file references, interpolation expressions and YAML comments stay on the server. Referenced fields omit both raw and effective values from the editor snapshot; the browser never round-trips current secret values. Connection settings, sockets, credentials, TLS, registry configuration and agent configuration remain outside this editor. Other configuration panels and label-backed settings are not made editable by this four-field feature.

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.

Digest-watch default

Set DD_DEFAULTS_WATCH_DIGEST=false to turn digest watching off by default for every Docker watcher owned by this Drydock process. Set dd.watch.digest=true on the containers that should still detect same-tag image rebuilds. true enables digest watching by default, and omitting the setting preserves automatic detection. Only true and false are accepted; an invalid or empty value prevents startup.

Precedence, highest first: the dd.watch.digest container label, a matching image set's WATCH_DIGEST, DD_DEFAULTS_WATCH_DIGEST, then automatic detection. Explicit false values remain overrides, even when the process default is true. Turning digest watching off also affects digest-pinned references; tag selection rules are unchanged.

The equivalent drydock.yml setting is:

defaults:
  watch:
    digest: false

The environment overrides the file. Restart Drydock after changing this default; it is not a live watcher-editor field. Existing stored containers pick up the default on their next discovery refresh.

Agent watchers use their agent process's configuration. Set the same variable or YAML setting on each Drydock agent that should use the default; setting it on the controller does not override remote agents' configuration. Native Portwing watchers continue to use Portwing's own configuration.

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. On the next restart the controller drops the container records its own watchers used to own, so a container that has moved to an agent is reported by that agent instead of staying stuck on what the controller last saw. Anything set on those records from the UI travels with the container: a snooze, a maturity mode and skipped tags or digests are stashed under the container's Docker id and land on the agent's copy when it reports in.
• 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, drydock keeps scanning on its CRON and defers only the automatic install, which it applies as soon as the window opens. Set MAINTENANCE_WINDOW_SCOPE=scan to skip the scan outside the window instead, which is what releases before v1.8.0 did. Either way the window gates drydock's own automatic behavior only. Manual updates from the UI or API always run. See Maintenance window.
• 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 an informational Major/Minor/Patch state rather than Current, but does not expose an update action; the pinned tag itself is indicated separately by a persistent pin glyph on the Tag cell, whose tooltip names dd.tag.family=loose / dd.tag.include as the remedy. 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.
• As of v1.8 (#1133), a candidate tag has to carry the same variant suffix as the current tag, letter for letter: -alpine never climbs to -alpine-perl or -alpine-slim, and it doesn't climb the other way either. Digit runs inside a suffix count as precision, not identity, so 1.27-alpine3.20 can climb to 1.28-alpine3.21, 12.1-cuda12 can climb to 12.2-cuda13, and a bare -alpine can refine to -alpine3.21 when that's the only newer build published. When both an exact-suffix and a digit-shifted candidate exist, the exact suffix ranks first. A trailing dot or other punctuation-only difference is never the same family, so 1.3.0-alpine. is not 1.3.0-alpine. Users who need a digit to be part of the identity, for example pinning to -cuda12, should use dd.tag.include with a regex that fixes that digit.

Variable examples

Watch the local docker host every day at 1am

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

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

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

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

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

Watch a remote docker host behind HTTPS with OIDC 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=OIDC
        - DD_WATCHER_MYREMOTEHOST_AUTH_OIDC_TOKENURL=https://idp.example.com/oauth/token
        - DD_WATCHER_MYREMOTEHOST_AUTH_OIDC_CLIENTID=my-client-id
        - DD_WATCHER_MYREMOTEHOST_AUTH_OIDC_CLIENTSECRET=my-client-secret

Drydock requests a client_credentials token from AUTH_OIDC_TOKENURL and refreshes it automatically before it expires. Optional variables narrow or extend the request: AUTH_OIDC_SCOPE, AUTH_OIDC_AUDIENCE, and AUTH_OIDC_RESOURCE scope the token; AUTH_OIDC_GRANTTYPE overrides the auto-detected grant type; AUTH_OIDC_DEVICEURL switches to the device-authorization flow.

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

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. This is still the recommended path — it's the most predictable option and works with every Drydock release.

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

Known limitations and tested versions

Drydock also detects Podman at watcher startup from the daemon's own /version response and logs a one-time warning naming the version and known limits, so it's obvious from the logs alone that a watcher is talking to Podman rather than Docker.

Known limits:

• Rootless networking — can differ from Docker bridge behavior; see Podman FAQ
• Volume driver differences — Podman's volume drivers don't behave identically to Docker's
• Containers managed by a systemd unit (Quadlet) are recreated by the Docker action outside their unit — the Docker action stops, removes, and recreates a container the same way regardless of what's managing it, so a Quadlet-managed container gets rebuilt outside its unit instead of being restarted through it; exclude systemd-managed containers from actions, or use a command action that restarts the unit instead

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

Maintenance window

A maintenance window restricts when drydock is allowed to act on an update by itself. That covers every action trigger, not only the ones that install an image: docker, dockercompose and portainer apply the update, and command runs the shell command you attached to it. Notification triggers are never gated, so drydock still tells you about an update the moment it finds one.

Outside the window the action is deferred rather than dropped, and drydock arms a catch-up that checks once a minute. When the window opens the catch-up re-runs the watcher's scan, so a trigger in simple or batch mode acts on that scan. A trigger in digest mode is told the window opened and flushes the updates it deferred right then, rather than holding them until its next DIGESTCRON.

By default the window has no effect on looking. Scheduled scans keep running on the watcher's own CRON, so new containers still appear, container state in the UI stays current, and update notifications still go out at the moment an update is found rather than hours later. MAINTENANCE_WINDOW_SCOPE chooses between that and the older whole-scan behaviour:

Set MAINTENANCE_WINDOW_SCOPE=scan to restore the behaviour of releases before v1.8.0.

The hold applies to a container watched by a remote agent the same way it applies to one on the controller's own watchers: the controller reads the window state the agent reports and holds the automatic install back until the agent's next report shows the window open.

The window never applies to you. Manual updates from the UI or API are not gated by it — the container's Update action stays available at any hour. When you use it outside the window, the confirm dialog notes that the update is currently policy-blocked with "Outside maintenance window — auto update deferred until the window opens" and the button reads Update anyway. That is a heads-up, not a refusal. See Update Eligibility & Blockers.

A manual recheck is not gated. The recheck-all action on the containers view, or calling POST /api/v1/containers/watch (all watchers) or POST /api/v1/containers/{id}/watch (a single container) directly, runs immediately regardless of the window. Those calls go straight to the watcher's watch() method, which the maintenance-window check never sits in front of. This is the watcher recheck, not the security Scan now action, which calls /scan and is unrelated to the window. Only the scheduled cron tick (and the queued catch-up it leaves behind) is gated.

Only allow automatic updates 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=* 2-3 * * *
      - DD_WATCHER_LOCAL_MAINTENANCE_WINDOW_TZ=Europe/Berlin

The evaluated timezone is MAINTENANCE_WINDOW_TZ, defaulting to UTC — not the host clock or your browser. The dashboard shows which watchers have a window and when the next one opens.

dd_watcher_maintenance_deferred_updates_total{type,name} counts the automatic updates the window held back, one per container per dispatch evaluation, including a container held back because something it depends on was. dd_watcher_maintenance_skip_total{type,name} keeps its old meaning, one per skipped scan cycle, so it only moves under MAINTENANCE_WINDOW_SCOPE=scan.

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.display.name, dd.display.icon, dd.depends_on, dd.depends_on.action, dd.notification.include, dd.notification.exclude, dd.action.include, dd.action.exclude and dd.action.auto can also be overridden by Drydock itself, per container, without touching the label. See Override labels with the API.

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. Image defaults after an update covers how drydock decides.

Portainer is an action trigger, so dd.action.include and dd.action.exclude apply to it like Docker and Docker Compose actions. Portainer still requires its local Compose identity and is never routed through an agent.

Override labels with the API

On the v1.8.0-rc.1 candidate, Drydock can store its own value for nine label-owned fields: the display name and icon, dd.depends_on and dd.depends_on.action, and the notification and action include, exclude and auto routing. This is for changing a container's behavior when you can't or don't want to edit its Compose file or recreate it. Saving an override never edits a Compose file, calls Docker, recreates or restarts a container, or runs a trigger. The endpoints and request format are in the Container API.

Each field resolves on its own, from lowest to highest priority:

A list override replaces the label's list whole and never merges with it. An empty list is an explicit "none": for dependencies it means no dependencies even when Compose declares some, and for a routing field it removes the label's value instead of falling back to it. Removing an override reveals the current label value again.

An override belongs to the container identity (watcher, agent and name, or the Compose project and service), not to a Docker id. It survives recreating the container, restarting Drydock and updating Drydock, and it has no expiry. For a Compose container the identity is the service, so every replica shares one override. Two limits follow from that. An override still applies to a different container that later takes the same name or Compose service, and the stored row stays visible in GET /api/v1/label-overrides when no container matches. Renaming a plain container, switching it between docker run and Compose, or moving it to another watcher or agent gives it a new identity, so the old override stops applying and has to be set again.

On a traditional agent, the agent checks action routing against its own labels again before it acts, so an override there can only narrow access: dd.action.include and dd.action.auto overrides may only list references the label lists too (none at all when the label has no include), with no wider threshold, and a dd.action.exclude override must start with the label's entries in order and may add more after them. Drydock applies the same rule each time the container is written, so a later label change is never cancelled by a stored override. Portwing controller-transport containers and containers on the controller are not restricted. Notification routing, display and dependency waves always run on the controller, so overrides apply fully to agent containers.

Labels stay what Docker reports. The Labels tab and label search keep showing the raw labels, and an override only changes the effective value Drydock uses. Admission messages say when the include or exclude that blocked an update is an override ("by the Drydock override of dd.action.exclude").

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, group, 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

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

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

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

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

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

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+$$

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....

Grammar

• Regex flavor is RE2, the same engine used by dd.tag.include/dd.tag.exclude (see RE2 syntax), not JavaScript regex. RE2 has no lookahead/lookbehind and no backreferences (\1) — those fail to compile. Inline flags like (?i) for case-insensitive matching are supported and are the only way to get case-insensitive matching; matching is case-sensitive by default.
• The separator is the first => in the formula. Everything before it (trimmed) is the pattern; everything after it (trimmed) is the replacement. Whitespace around => is optional (pattern=>replacement works the same as pattern => replacement). Only one pattern/replacement pair is supported per label — there is no chaining or delimiter for multiple transforms.
• A formula with no => is ignored. The tag passes through unchanged; this is not treated as an error.
• An empty or unset dd.tag.transform is a no-op — the tag passes through unchanged.
• Replacement placeholders are $1, $2, $3... referencing capturing groups in the pattern, in the order they appear (not by name). A placeholder that references a group the pattern doesn't have, or a group that didn't participate in the match, is replaced with an empty string rather than left literal or causing an error. A replacement with no placeholders at all is a valid way to force a constant value (e.g. ^v(.+)$ => stable).
• When the pattern doesn't match the tag, the original tag is returned unchanged — the replacement is never applied partially.
• Anchoring is up to you. RE2 (like most regex engines) matches anywhere in the string unless you anchor with ^/$; the worked examples below all anchor explicitly, which is the recommended default for a transform since an unanchored pattern can match more of the tag than intended.
• Patterns are capped at 1024 characters. Longer patterns fail to compile — see the callout above for what that does at runtime.

Interaction with include/exclude and semver comparison

dd.tag.include/dd.tag.exclude are matched against the raw tags returned by the registry, before any transform is applied — the transform never changes which tags are considered candidates. dd.tag.transform is applied afterward, to both the current tag and each surviving candidate, and it's the transformed value that gets semver-parsed, family-matched, and compared to decide whether an update is available and what precision (tagPrecision) and family shape the tag has. In other words: use include/exclude to narrow down which tags are in play using their real names, and transform to reshape those tags into something semver-comparable. The ${transformed} variable in dd.link.template is this same post-transform value.

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

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

Associate a link to the container version

You can associate a browsable link to the container version — a GitHub release, a changelog page, a registry tag search — using a templated string. Drydock renders the template once per container, computes it onto container.link and container.result.link, and the UI's release-notes/release-link action surfaces it wherever that container is shown.

Set it with the dd.link.template label, or with DD_WATCHER_{watcher_name}_IMGSET_{imgset_name}_LINK_TEMPLATE on a matching image set preset when many containers of the same image should share one template. A per-container dd.link.template label always wins over a matching imgset's LINK_TEMPLATE — see Imgset precedence.

Placeholders

A placeholder outside this set (e.g. ${bogus}) is silently replaced with an empty string — the template is never rejected and nothing is logged.

Worked examples

GitHub release link from ${major}.${minor}.${patch} — Traefik tags carry a v prefix (v3.1.4) that has to come off before the value parses as semver, so dd.tag.transform strips it and the template rebuilds the release URL from the parsed segments:

docker run -d --name traefik \
  --label 'dd.tag.transform=^v(.*)$ => $1' \
  --label 'dd.link.template=https://github.com/traefik/traefik/releases/tag/v${major}.${minor}.${patch}' \
  traefik:v3.1.4

Tag v3.1.4 renders https://github.com/traefik/traefik/releases/tag/v3.1.4.

Changelog link using ${transformed} — Postgres tags carry a variant suffix (16.4-alpine) the changelog URL doesn't use, so the transform trims it to major.minor and the template uses that value directly instead of rebuilding it from ${major}/${minor}:

docker run -d --name postgres \
  --label 'dd.tag.transform=^(\d+\.\d+).*$ => $1' \
  --label 'dd.link.template=https://www.postgresql.org/docs/release/${transformed}/' \
  postgres:16.4-alpine

Tag 16.4-alpine renders https://www.postgresql.org/docs/release/16.4/.

Registry link using ${raw} — no transform is needed to point at a registry's own tag listing, since the raw tag is exactly what the registry expects in the query string:

docker run -d --name mariadb \
  --label 'dd.link.template=https://hub.docker.com/_/mariadb?tab=tags&name=${raw}' \
  mariadb:10.6.4-jammy

Tag 10.6.4-jammy renders https://hub.docker.com/_/mariadb?tab=tags&name=10.6.4-jammy.

services:

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

Failure behavior

• Unknown placeholder: substituted with an empty string. The template still renders and drydock never rejects or logs it — a typo like ${majro} quietly produces a broken-looking URL instead of an error.
• Invalid or non-http(s) URL: drydock doesn't validate the rendered value at all — any string is accepted and stored on container.link/result.link. The UI's release-link action only renders it as a clickable link when the rendered string starts with http:// or https:// (case-insensitive); anything else (a bare path, a javascript: URL, malformed output from an unmatched transform) is silently dropped from the UI instead of shown broken.

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

Label a specific port

You can attach a custom label to one of a container's published ports. It's shown on the clickable port link in the container list and detail views instead of the raw hostPort->containerPort/protocol mapping. Keys are <port>=<label> pairs, comma-separated for multiple ports; a bare port number matches /tcp by default.

services:

  traefik:
    image: traefik:3
    ports:
      - "80:80"
      - "8443:443"
    labels:
      - dd.port.label=80=Web UI,443=Admin Console

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

• 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:

In the UI, each host-published port in details.ports renders as a clickable link (opened in a new tab). The target scheme is auto-detected from the container-side port — 443 and 8443 get https://, everything else gets http:// — and the host is the published HostIp when it's a real bindable address, falling back to the agent's configured host for agent-watched containers, or the browser's own hostname otherwise. Internal-only (unpublished) ports render as plain text. Use dd.port.label to give a port a friendly display name instead of the raw mapping.

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.

In v1.8.0-rc.1, digest checks also retain the remote candidate's OCI version label in the API's result.softwareVersion field when the selected platform's image config provides it. This optional field is separate from the installed image.softwareVersion shown in the Version column. Missing or unusable labels leave it absent. The label alone does not enable a gate. Release-count maturity uses this candidate version or bounded digest proof only when its policy is configured.

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 tag names a specific version (the shape-based tagPinned field, e.g. 1.4.5, 16-alpine, v3) — not containers whose tagPrecision is specific. Rolling aliases like latest and stable, and bare distro/variant tags like alpine, slim, and bookworm, are never considered pinned even though they contain no version number. 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.

Native socket proxy

The root cause of proxy-timeout reconnects is that Drydock cannot control idle timeout behavior on third-party proxies.

Reduce proxy-timeout reconnect churn

To 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.