Tracking Docker Image Updates in a Home Lab with WUD

The problem

Every service in home lab is a Docker Compose stack with a pinned image tag:

1
services:
2
  immich-server:
3
    image: ghcr.io/immich-app/immich-server:v3.3.5
4
    # rest of config
5

6
  homeassistant:
7
    image: ghcr.io/home-assistant/home-assistant:2026.10.2
8
    # rest of config
9

10
  grafana:
11
    image: grafana/grafana:13.2.4
12
    # rest of config

Now, to get info about new version, I would have to manually check each image’s repository for updates. With ~40 containers across a many different compose files, “check for updates” means visiting a dozen GitHub release pages.

Potential solutions

The usual answer is Watchtower - a container that pulls new images and restarts containers automatically. But that goes against the principle of pinning: I don’t want my containers to update automatically. I just want to be informed about new versions. What is more, I have no idea which version each container is currently running without inspecting the compose files or querying the Docker daemon.

Also there are problems with breaking changes: if an image updates automatically, it might introduce changes that are incompatible with my setup. At the end, backup strategy is the critical part: if an image updates automatically and breaks something, I need a way to roll back to a known good state.

Human-in-the-loop approach

The idea is to have a system that monitors for updates but leaves the decision-making to the human operator. This way, I can stay informed about new versions without risking automatic updates that might break my setup.

The expected solution is to have a tool that continuously monitors the Docker environment for updates and reports them, while leaving the actual update process to the human operator. Because I am using pinned tags for my containers (in docker-compose files), I need a tool that can detect updates and can apply them automatically to the compose files, but only when I decide to do so.

What WUD is

After some research and experimentation, I found that WUD perfectly fits the human-in-the-loop approach I described above.

WUD (What’s Up Docker, source on GitHub) is a single container that:

• Watches the Docker daemon through the socket and lists every running container with its image and tag.
• Looks up each image in its registry (Docker Hub, GHCR, LSCR, Quay and many more are built in) and compares the running tag with the tags available upstream.
• Reports the result through a REST API, and optionally through triggers - SMTP, Slack, Telegram, MQTT and others.

The important part is what it doesn’t do by default: it never pulls, never restarts, never edits a file. It only detects. For a pinned-tag setup that’s exactly the right split.

The setup

Following the convention from the earlier parts of this series, it gets its own folder with its own docker-compose.yml:

1
services:
2
  wud:
3
    container_name: wud
4
    image: getwud/wud:9.5.0
5
    volumes:
6
      - /var/run/docker.sock:/var/run/docker.sock:ro
7
      - ./wud/store:/store
8
    restart: unless-stopped
9
    environment:
10
      - WUD_WATCHER_LOCAL_CRON=0 6 * * *
11
      - WUD_AUTH_ADMIN_USER=${WUD_ADMIN_USER}
12
      - WUD_AUTH_ADMIN_PASSWORD=${WUD_ADMIN_PASSWORD}

What it looks like in practice

Start the stack and WUD lists every container on the host with its current tag, flagging the ones with a newer version available. The data is exposed through the API, which is what the rest of this post builds on. A trimmed response for one container that has an update pending:

1
{
2
  "name": "homeassistant",
3
  "watcher": "local",
4
  "updateAvailable": true,
5
  "updateKind": {
6
    "kind": "tag",
7
    "localValue": "2026.10.2",
8
    "remoteValue": "2026.10.3",
9
    "semverDiff": "patch"
10
  },
11
  "image": {
12
    "name": "homeassistant/home-assistant",
13
    "tag": { "value": "2026.10.2", "semver": true }
14
  },
15
  "result": { "tag": "2026.10.3" },
16
  "labels": {
17
    "com.docker.compose.service": "homeassistant",
18
    "com.docker.compose.project.config_files": "smart-home/docker-compose.yml"
19
  }
20
}

Two parts of that response worth to mention:

• updateKind.semverDiff says how big the jump is - patch, minor or major. That’s the number that decides whether I read release notes first.
• labels contains the com.docker.compose.* labels that Docker Compose attaches to every container it creates. They hold the exact path of the compose file that created the container. That’s a free mapping from “this container is outdated” to “this is the file to edit”.

Omit pre-release tags

Out of the box WUD recommends the newest tag it can find, and registries are full of tags that aren’t releases: dev, rc, nightly, -ubuntu variants, an immich tag with an -openvino suffix. Two labels on the container filter them at the source:

1
portainer:
2
  image: portainer/portainer-ce:2.45.3-alpine
3
  labels:
4
    # Only track the -alpine variant; ignore plain tags like 2.42.0.
5
    - wud.tag.include=^\d+\.\d+\.\d+-alpine$$
6

7
immich-machine-learning:
8
  image: ghcr.io/immich-app/immich-machine-learning:v3.3.5-openvino
9
  labels:
10
    # track only the -openvino variant; ignore plain tags like v3.3.5.
11
    - wud.tag.include=^v\d+\.\d+\.\d+-openvino$$

wud.tag.include is a regex that a tag has to match to be considered, and wud.tag.exclude removes tags that match.

From “update available” to a compose diff

Now the problem is half solved. I don’t want automatic updates and I don’t want latest (or any floating tag), so the only way to apply an update is to bump the version in the compose file myself. The flow is simple:

1. Ask WUD what is out of date.
2. Based on the response, bump the version in the right compose file.

With ~40 containers that is a long, boring job, and the kind of thing that stops happening. So I wrote a script that does it. It’s a small Bash script (jq, curl, perl) that lives in the same repository as the compose files, and it does exactly this:

1. Asks the WUD API for the list of containers.
2. For every outdated one, finds the compose file, the service and the old version.
3. Replaces the old version with the new one in that file.
4. Prints the command to deploy the change - it never pulls images or restarts anything.

1
🔎 Querying WUD ...
2

3
📦 Updates available:
4
     #  CONTAINER              FILE                               CHANGE
5
     1  homeassistant          smart-home/docker-compose.yml      home-assistant:2026.10.2  →  home-assistant:2026.10.3

That’s real output from the server. As you can see, it lists the container, the compose file, and the change from the old tag to the new one. What is more I can run interactive updates with the script, selecting which updates to apply and which to skip.

1
Review first with:  git diff -- '*docker-compose*'
2

3
🚀 To pull and redeploy the updated services:
4
   docker compose -f "smart-home/docker-compose.yml" up -d --pull always homeassistant

If the changes look fine, I run the printed docker compose command, check that the service came back healthy and commit.

The final solution

• Every day at 06:00, WUD scans the host and updates its list of available container updates.
• When I have a few minutes - I run the script to check for available updates and apply them selectively.
• Run back-ups if necessary - Before applying updates, ensure that I have recent backups.
• After applying updates - I review the changes, run the necessary docker compose commands, and commit the updates to the repository.