Diun Docker Setup Guide: Update Notifications Without the Restarts

What Is Diun?

Diun — Docker Image Update Notifier — is an open-source tool by crazymax (image crazymax/diun, docs at crazymax.dev/diun). It inspects the images your containers are running, compares their digests against the registry, and notifies you when a newer image is available. That is all it does. It never pulls the image for you, never recreates the container, and never restarts anything.

This notify-only design is exactly why many homelab users choose it over auto-updaters. It is the classic counterpoint to Watchtower — see Watchtower vs Diun for the full head-to-head — and a good fit if you left the archived original Watchtower but do not want fully automatic restarts. It also complements Watchtower: some users run Diun for awareness and the maintained nickfedor Watchtower fork on a small set of non-critical services.

Prerequisites

You need a working Docker host (Docker Engine or a rootless setup) with the Compose plugin, plus access to your registry credentials if you watch private images. Notifications go through providers configured in a diun.yml file or via environment variables — have at least one destination ready (a Discord webhook or an SMTP account is the easiest start).

Docker Compose Setup

Create a project directory with two files: docker-compose.yml and diun.yml. The Compose file below is the canonical layout from the Diun docs:

services:
diun:
  image: crazymax/diun:latest
  container_name: diun
  command: serve
  volumes:
    - "./diun-data:/data"
    - "/var/run/docker.sock:/var/run/docker.sock"
  environment:
    - "TZ=UTC"
    - "DIUN_WATCH_WORKERS=20"
  restart: always

The pieces:

• command: serve — starts Diun's polling daemon. This is the normal long-running mode.
• ./diun-data:/data — persists Diun's database so it remembers which image digests it has already seen (and therefore does not re-notify you after a restart).
• /var/run/docker.sock:/var/run/docker.sock — lets Diun list your running containers and their images.
• TZ — keeps schedules and log timestamps in a timezone you understand.

The companion diun.yml file lives in the same directory (Diun reads it from its working directory) and configures what to watch and where to notify. Start minimal — notification providers come next — and then bring the stack up with docker compose up -d. Check docker compose logs -f diun for the first poll.

Watching Specific Images

Diun can watch two kinds of targets: Docker providers (running containers discovered through the socket) and file providers (static lists of images in diun.yml).

Watching running containers is the default: Diun inspects each container's image and tracks its digest. For images you do not run yet — or services managed outside this host — declare them explicitly:

watch:
workers: 20
schedule: "0 */6 * * * *"
firstCheckNotif: true

defaults:
sortTags:
  - semver
notifyOn:
  - new

items:
- image: nginx
- image: ghcr.io/myorg/myapp:latest

Key options: notifyOn: new notifies only when a new image version appears (not on every digest change); sortTags: semver is useful for repos with semantic tags; and firstCheckNotif: true sends a summary after the first poll so you can confirm everything is wired up.

Notifications: Discord

Diun's notification configuration follows a Shoutrrr-style provider model. A Discord webhook is the quickest way to get working alerts. Create a webhook in your Discord server (Server Settings → Integrations → Webhooks), then add it to diun.yml:

notif:
discord:
  webhookURL: "https://discord.com/api/webhooks/1234567890/AbCdEfGhIjKlMnOpQrStUvWxYz"
  timeout: 10s
  templateBody: |
    Docker tag {{ .Entry.Image }} has been released.

Diun notification URLs follow the Shoutrrr format used by Watchtower notifications as well — for example discord://TOKEN@CHANNEL_ID, telegram://TOKEN@telegram?channels=CHANNEL, slack://TOKEN@CHANNEL, and smtp://USER:PASS@smtp.host:587/?fromaddr=SENDER&toaddr=RECEIVER. If you already set up Watchtower notifications, you already know this URL syntax.

Notifications: Email via SMTP

For email alerts, configure the SMTP provider with your mail server details:

notif:
mail:
  host: smtp.example.com
  port: 587
  username: diun@example.com
  password: "your-app-password"
  from: diun@example.com
  to:
    - you@example.com
  ssl: true

Tips from experience: use an app-specific password rather than your main account password, and verify the SMTP host allows relaying from your server's IP (Gmail, for example, requires an app password with 2FA). You can enable both Discord and email simultaneously — Diun fans out notifications to every configured provider. Email is the better choice for alerts you might need to search later; Discord is better for at-a-glance awareness.

Schedule Configuration

Diun uses cron-style schedules for its watch interval. The schedule lives under watch.schedule in diun.yml:

watch:
schedule: "0 */6 * * * *"
workers: 20
firstCheckNotif: false

Diun's cron expressions support seconds as the first field (like Watchtower's WATCHTOWER_SCHEDULE, where 0 0 4 * * * means daily at 04:00). The example above — 0 */6 * * * * — polls every six hours. Set workers to match your image count; 20 is comfortable for most homelabs. More frequent than hourly is rarely useful: registries do not move that fast, and you will just burn API rate limits.

One more scheduling tip: align your poll times with your own availability. If you check Discord in the morning, a schedule like 0 0 7 * * * (daily at 07:00) means fresh notifications greet you with your coffee instead of arriving while you sleep. Since Diun never acts on its own, the "best" schedule is simply the one whose alerts you will actually read and act on.

Verifying Your Setup

After docker compose up -d, confirm Diun is healthy before trusting it:

• Run docker compose logs -f diun and look for the first analysis cycle completing without errors. Connection failures to a registry or a misconfigured provider show up here first.
• If you set firstCheckNotif: true, you should receive a summary notification through every configured provider after the first poll — this confirms the whole chain from registry check to Discord or email works.
• Check that ./diun-data contains Diun's database file. This state is what prevents duplicate notifications after a container restart, so make sure the volume is actually persisted and not lost on recreation.

If the first poll finds updates for images you already run, that is normal — it means Diun is working. What you do next is up to you: read the upstream changelog, then docker compose pull && docker compose up -d for that service on your own schedule.

Keeping Diun Itself Updated

One thing Diun will not do is update itself. Like any container, it needs a periodic pull and recreate:

docker compose pull diun
docker compose up -d diun

A reasonable rhythm is monthly, or whenever you see a release note that matters to you. Some users run Watchtower in monitor-only mode pointed at Diun itself — Watchtower watches, Diun notifies, and you stay the one who decides when restarts happen. Either way, do not forget the notifier in your maintenance routine.

Diun vs Watchtower: Quick Comparison

Still deciding? The deep dive at Watchtower vs Diun covers tradeoffs in detail, and Watchtower alternatives lists other options beyond these two. If you hit issues during setup, the troubleshooting index covers the most common notification and socket problems.

When to Choose Diun

• Databases and stateful services. Automatic restarts of Postgres, Redis, or a message queue mid-write are the classic homelab horror story. Diun lets you see the update, read the changelog, back up, and restart on your terms.
• Manual control / staged rollouts. If you update staging first and production later, notifications give you the trigger without the action.
• You want an audit trail of updates. Diun's notification history is a changelog of what became available, decoupled from what you actually applied.
• You already distrust unattended restarts — especially if the Watchtower archive news made you reconsider. Diun is the gentle off-ramp: same awareness, zero automation risk.

The honest tradeoff: Diun does not keep you patched automatically. The notification only helps if you act on it. Pair it with a weekly habit — or run Watchtower in monitor-only mode on stateless services alongside Diun — and you get awareness everywhere and automation only where it is safe.