Docker Watchers

Watchers are responsible for scanning Docker containers.

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

Variables

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/ca.pem:/certs/cert.pem:ro
        - /my-host/my-certs/ca.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/ca.pem:/certs/cert.pem:ro \
    -v /my-host/my-certs/ca.pem:/certs/key.pem:ro \
  ...
  codeswhat/drydock

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
    healthcheck:
      test: wget --spider http://localhost:2375/version || exit 1
      interval: 5s
      timeout: 3s
      retries: 3
      start_period: 5s
    restart: unless-stopped

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 for multi-host setups or when you want to completely avoid socket mounts.

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

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

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.

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}_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

Imgset precedence

• dd.* labels on the container (or swarm service/container merged labels) are highest priority.
• IMGSET values are defaults applied only when the corresponding label is not set.

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.

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

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, you can indicate that you want to watch x.y.z versions only

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

Additionally to semver tag tracking, you can also track if the digest associated to the local tag has been updated.
It can be convenient to monitor image tags known to be overridden (latest, 10, 10.6...)

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.trigger.include=smtp.gmail,dockercompose.local:minor

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

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:

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.