Diun – the safe alternative to watchtower?

If you run a lot of Docker containers you need some mechanism to let you know about updates. Watchtower is a popular solution I also used but the auto-update feature can be dangerous. Diun is a very lightweight alternative that takes the safer approach of only notifying you.

Docker image versioning

If you run any Docker container then you are running an instance of a certain image (basically the “manual” of what software to include and to run). These images will (or at least should) be updated over time by their author.

If you are using docker-compose like I am doing for my smarthome server then it is easy to spot these versions. The image keyword is followed by the container name, a colon and the version. For example image: grafana/loki:2.3.0 means I am running the Loki image from Grafana (for log aggregation) using the version 2.3.0.

In case you don’t specify any version (e.g. image: grafana/loki) Docker will default to the latest version. To make that clear I try to usually define all my images either using a specific version number or at least :latest. This makes the intent of using the most up to date version very clear.

To stay safe it makes sense to keep applying these updates in most cases. I described possible update flows for this approach here, using Home Assistant as an example.

The problem with automatic updates

Keeping your images up to date manually can become very tedious very quickly if you run a lot of containers. To avoid all that manual work I set up Watchtower some time ago. Watchtower is a software running in another container that can notify you about updates and apply them automatically. You can read all the details about my Watchtower setup here.

The problem with automatic updates is a loss of control though. Your containers will be restarted without your input at possibly inopportune times and new versions can include unwanted, sometimes even breaking changes that you then have to deal with.

To avoid that I did set specific versions for most of my containers and fully disabled Watchtower (via labels) for important containers like Home Assistant and the Unifi Controller for my network. I feel like in many cases the Watchtower auto-update has become more of nuisance for me. Fortunately I found a great alternative.

Diun for update notifications

While of course Watchtower can be configured to not update and only notify there is also a nice, lightweight alternative out there that is built only for image update notifications: Diun. This small Go software is available as another container and runs with very little resources (<8MB RAM and <1% CPU on my Pi 4).

The setup via docker-compose is quite simple and it supports a good range of notification services (Discord, mail, MQTT, Slack, Webhook, …). I decided to use Pushover like I do for other projects too. Diun will NOT do any automatic updates but I have set it to send me a reminder about available updates at the end of the week so I can spare a couple minutes on the weekend to run them if I feel it is necessary.

This is my setup:

diun:
    container_name: diun
    image: crazymax/diun:4.26
    command: serve
    volumes:
      - ${DATADIR}/diun/data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - TZ=${TZ}
      - DIUN_WATCH_SCHEDULE=0 19 * * FRI,SAT,SUN
      - DIUN_PROVIDERS_DOCKER=true
      - DIUN_PROVIDERS_DOCKER_WATCHBYDEFAULT=true
      - DIUN_NOTIF_PUSHOVER_TOKEN=${DIUN_PO_TOKEN}
      - DIUN_NOTIF_PUSHOVER_RECIPIENT=${DIUN_PO_RECIPIENT}
    restart: unless-stopped
    logging:
      driver: loki
      options:
        loki-url: "http://localhost:3100/loki/api/v1/push"
        max-size: "100m"

As always there is a bit of boilerplate code. The whole logging part is only relevant if you run Loki, the container name and restart settings are also not strictly needed.

I pinned the image version to 4.26 but will update it from time to time. The command: serve is needed according to the manual. This will override the default command. The interesting parts are the volumes and environment variables.

The volume maps the Docker socket and a configuration storage folder. Passing the Docker socket should be considered carefully as this allows access to all other running Docker containers. In this case it is needed though to find running containers and possible updates.

The data folder can be mapped to any path on your server, I defined one using a shared variable ${DATADIR} that points to my data storage. The variable is defined in a .env file. This mapping is needed to preserve configurations even during container restarts.

All configurations are quite well described in the manual and can be set either via a configuration file (that would also need to be mapped) or, and I decided to go this way, via environment variables.

The environment variables define the timezone and a schedule when to run the update check. The schedule is provided as cron and I decided to get notifications every Friday, Saturday and Sunday at 19:00 in the evening.

The DIUN_PROVIDERS_DOCKER tells Diun to search for running Docker containers and extract their version to check for updates. This needs the access to the Docker socket.

Control which images to check for updates

You can control which images should be checked. Either you set DIUN_PROVIDERS_DOCKER_WATCHBYDEFAULT to true to check all containers by default (and possibly disable some via labels) or you set the following label on any container you want to check:

labels:
      - diun.enable=true

There is also a DIUN_PROVIDERS_DOCKER_WATCHSTOPPED flag for including stopped containers in the checks. Here is the log output showing all the checks for my containers:

Interestingly it seems to fail in some cases to find 32bit ARM images. No problem though, I am planning to migrate to a 64bit OS soon anyways.

Sending notifications via Pushover

There are two variables regarding Pushover notifications. One will provide a recipient (thats the user key from your user in Pushover) and one a Pushover token (that is the sender identity, you can create one via the settings and “Your Applications”). Again both of them are variables that can be found in the .env file.

If needed you can also change the template title and body to your liking but I am so far happy with the default settings.