Diun: Get Notified When Docker Images Are Updated

Keeping container images up to date is a balancing act. Auto-updating everything with Watchtower is convenient but risky — a breaking change can take down a service without warning. Manually checking for updates is tedious and easy to forget.

Photo by Lorenzo Herrera on Unsplash

Diun sits in the middle: it watches your containers, checks registries for new image versions, and sends you a notification. You decide when and how to update. No automatic changes to your running stack.

What Diun Does

Diun periodically queries Docker registries (Docker Hub, GHCR, Quay.io, or private registries) for new image versions. When a new digest or tag is found, it sends a notification to your configured channel — Slack, Discord, Ntfy, email, Telegram, or others.

It doesn't pull or restart anything. It just tells you what's available and lets you decide what to do.

Installation

Deploy Diun alongside your Docker setup:

services:
  diun:
    image: crazymax/diun:latest
    container_name: diun
    command: serve
    restart: unless-stopped
    volumes:
      - diun-data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      TZ: America/Los_Angeles
      LOG_LEVEL: info
      DIUN_WATCH_SCHEDULE: "0 */6 * * *"   # every 6 hours
      DIUN_WATCH_JITTER: 30s
      DIUN_PROVIDERS_DOCKER: "true"
      DIUN_PROVIDERS_DOCKER_WATCHBYDEFAULT: "true"
      # Notification config added below

volumes:
  diun-data:

The Docker socket mount is required — Diun uses it to inspect running containers and discover what images they use.

Notification Channels

Configure at least one notification channel via environment variables:

Ntfy (self-hosted push notifications):

environment:
  DIUN_NOTIF_NTFY_ENDPOINT: https://ntfy.sh
  DIUN_NOTIF_NTFY_TOPIC: my-diun-alerts
  DIUN_NOTIF_NTFY_PRIORITY: default

Discord webhook:

environment:
  DIUN_NOTIF_DISCORD_WEBHOOKURL: https://discord.com/api/webhooks/xxx/yyy

Slack:

environment:
  DIUN_NOTIF_SLACK_WEBHOOKURL: https://hooks.slack.com/services/xxx/yyy/zzz

Email (SMTP):

environment:
  DIUN_NOTIF_MAIL_HOST: smtp.gmail.com
  DIUN_NOTIF_MAIL_PORT: 587
  DIUN_NOTIF_MAIL_USERNAME: [email protected]
  DIUN_NOTIF_MAIL_PASSWORD: your-app-password
  DIUN_NOTIF_MAIL_FROM: [email protected]
  DIUN_NOTIF_MAIL_TO: [email protected]

Gotify:

environment:
  DIUN_NOTIF_GOTIFY_ENDPOINT: https://gotify.yourdomain.com
  DIUN_NOTIF_GOTIFY_TOKEN: your-app-token

You can configure multiple notification channels simultaneously.

Providers: What Diun Watches

Diun uses "providers" to discover containers:

Docker provider (most common): Watches containers running on the local Docker host.

environment:
  DIUN_PROVIDERS_DOCKER: "true"
  DIUN_PROVIDERS_DOCKER_WATCHBYDEFAULT: "true"

With WATCHBYDEFAULT=true, every container is monitored. Set it to false and opt in per container with a label.

Docker Swarm: For Swarm deployments, use the swarm provider instead.

Kubernetes: Watches pods in specified namespaces.

Docker Compose: Point at a compose file directory to watch services defined there.

Container-Level Labels

With WATCHBYDEFAULT=false, add labels to specific containers to opt them in:

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    labels:
      - "diun.enable=true"
      - "diun.regopt=dockerhub"

You can also configure per-container watch settings:

labels:
  - "diun.enable=true"
  - "diun.watch_repo=true"    # watch all tags, not just the current one
  - "diun.include_tags=\\d+\\.\\d+\\.\\d+"  # only notify for semver tags

Registry Configuration

For private registries or to handle Docker Hub rate limits:

services:
  diun:
    environment:
      DIUN_REGOPTS_0_NAME: dockerhub
      DIUN_REGOPTS_0_USERNAME: your-dockerhub-username
      DIUN_REGOPTS_0_PASSWORD: your-pat-token

      DIUN_REGOPTS_1_NAME: ghcr
      DIUN_REGOPTS_1_USERNAME: your-github-username
      DIUN_REGOPTS_1_PASSWORD: your-github-pat
      DIUN_REGOPTS_1_SELECTOR: image
      DIUN_REGOPTS_1_IMAGESEL: ghcr.io

Docker Hub rate limits anonymous pulls to 100/6hr. Authenticating with a free account raises this to 200/6hr, which matters if you're monitoring many images.

Notification Format

A typical Diun notification looks like:

New Docker tag found for image nginx:latest
  Registry: index.docker.io
  Image:    nginx:latest
  Digest:   sha256:abc123...
  Platform: linux/amd64
  Status:   New

Notifications include the image name, new digest/tag, platform, and whether it's a new tag or an updated existing tag.

Watch Schedule

Control how often Diun checks for updates:

environment:
  # Cron syntax: every 6 hours
  DIUN_WATCH_SCHEDULE: "0 */6 * * *"

  # Or use predefined schedules
  # DIUN_WATCH_SCHEDULE: "@daily"
  # DIUN_WATCH_SCHEDULE: "@weekly"

  # Add jitter to avoid hammering registries at the same second
  DIUN_WATCH_JITTER: 30s

Once per day or every 6 hours is usually sufficient. More frequent polling increases Docker Hub API usage.

Diun vs. Watchtower

Use Diun when you want visibility into available updates without automatic changes — especially for production services.

Use Watchtower in --monitor-only mode for the same notification-only behavior, or with auto-updates for non-critical containers where breaking changes are acceptable.

Many setups use both: Diun for awareness, and manual docker pull && docker compose up -d for controlled updates.

Practical Workflow

With Diun running:

1. You receive a notification: "New image for traefik:latest"
2. You check the Traefik changelog for breaking changes
3. You pull the new image during a maintenance window
4. You test the updated container and confirm everything works

This is slower than auto-updates but safer — especially for infrastructure services like reverse proxies, databases, and authentication systems where unexpected breaking changes cause outages.

Getting Started

1. Add the Diun compose definition to your stack
2. Configure at least one notification channel
3. Set WATCHBYDEFAULT=true (easiest) or add labels to specific containers
4. Start Diun: docker compose up -d diun
5. Trigger an immediate check: docker exec diun diun watch
6. Verify notifications arrive

The project is at crazy-max/diun with active maintenance and thorough documentation covering all providers and notification channels.