Diun webhook endpoint to trigger image pull/redeploy (secrets-safe updates)

[FrostWalk]

Hi everyone,

First of all, I would like to thank @kimdre for this amazing project, finally, I can manage my infrastructure in declarative way without setting up Kubernetes on a single node.

Background

I run doco-cd on a normal Docker host (no Swarm) and to keep images up to date I used Watchtower (the fork of @beatkind who very kindly maintains the project), but I ran into an issue that’s hard to solve cleanly:

• Some services require secrets that are injected/templated at deploy time by doco-cd.
• When Watchtower updates an image, it recreates the container outside of doco-cd’s control.
• The recreated container can fail to start because the secrets/injected artifacts are not present (or not refreshed the same way) since the container was not spawned/redeployed by doco-cd.

So the outcome is: automatic image updates work for “simple” services, but “secret-dependent” services can break whenever Watchtower updates them.

I considered enabling force_image_pull and force_recreate in doco-cd, but I can’t keep those always-on (I don’t want frequent full recreates; it’s unsustainable for my setup). I would like to trigger a “force pull + recreate” only when there is actually an image update.

I know that automatically updating all containers is not considered best practice, but sometimes images with a fixed version receive updates to the base image.

Proposed feature

My idea is to switch from Watchtower to Diun, as the latter, in addition to being officially maintained, is able to generate webhooks containing various information, including images that can be updated.
Below is the JSON body that is sent by Diun:

{
  "diun_version": "4.24.0",
  "hostname": "myserver",
  "status": "new",
  "provider": "file",
  "image": "docker.io/crazymax/diun:latest",
  "hub_link": "https://hub.docker.com/r/crazymax/diun",
  "mime_type": "application/vnd.docker.distribution.manifest.list.v2+json",
  "digest": "sha256:216e3ae7de4ca8b553eb11ef7abda00651e79e537e85c46108284e5e91673e01",
  "created": "2020-03-26T12:23:56Z",
  "platform": "linux/amd64",
  "metadata": {
    "ctn_command": "diun serve",
    "ctn_createdat": "2022-12-29 10:22:15 +0100 CET",
    "ctn_id": "0dbd10e15b31add2c48856fd34451adabf50d276efa466fe19a8ef5fbd87ad7c",
    "ctn_names": "diun",
    "ctn_size": "0B",
    "ctn_state": "running",
    "ctn_status": "Up Less than a second (health: starting)"
  }
}

My idea is to create an endpoint in Doco-CD that receives that webhook (perhaps at regular, schedulable intervals), pools the new image, and recreates all the containers running that image (with the option to exclude some using labels or another method).

Expected behavior (high level):

• Accept Diun’s webhook JSON.
• Identify which compose project(s) are affected by image name and exclude containers that have the appropriate label
• Trigger a deploy for that target with “pull new image + recreate containers” semantics (equivalent to force_image_pull: true + force_recreate: true), but only for that triggered run.

This would let Diun act as a lightweight “image update detector”, while doco-cd remains the sole authority that actually manages container lifecycle.

Questions for the community

• Does this align with doco-cd’s scope/philosophy, or would you prefer keeping Diun integration out-of-tree?
• If in scope, what would be the preferred way to map a Diun event to a doco-cd target? (maybe labels or config mapping?)
• Would a more generic “redeploy with force pull/recreate for this run” endpoint be acceptable, with Diun support implemented as a third-party piece of software that adapts the payload?

Thanks again for doco-cd, and thanks in advance to anyone who shares thoughts or suggestions.

[kimdre]

I don't use Watchtower or Diun for my image updates but Renovate or Dependabot. I created doco-cd with these services in mind, since you can find all updates/changes in the Git repository history.

[FrostWalk]

Hi, thank you for your reply, that’s a really smart approach, and not something I had considered.

Could I ask how you handle images like Immich that use the latest tag, or images like Postgres where I pin only the major version (for example 18) and minor versions are released under the same tag? In these cases the tag stays the same, but the underlying image changes.

Can Dependabot or Renovate detect updates in this scenario? If yes, how do they pick them up and what mechanism do they use to trigger an update?

Thanks again.

[kimdre]

You can pin the image tag digest. Renovate is smart enough to detect this and then search for new versions by comparing the digests/hashes.

So for immich for example:

https://github.com/immich-app/immich/pkgs/container/immich-web/149034364?tag=release

- ghcr.io/immich-app/immich-web:release
+ ghcr.io/immich-app/immich-web:release@sha256:2bef28adbcc60a2ee5dee8cafe109e3d5c6b7bca88d90acdd3eec376200a6d6e

A example pull request would then look like this: #923

[FrostWalk]

Hi,
thanks for the explanation. I checked the wiki and noticed there isn’t any guidance on managing automatic updates. In my experience, this is really useful, and the Renovate-based approach works well. Would it make sense to add a dedicated section covering it?

P.S. Even without Diun, I think it would be helpful to add endpoints to recreate and re-pull images, and potentially support other actions. If you agree it would be useful, I’d be happy to implement the logic and open a PR.