Diun Documentation

Diun (Docker Image Update Notifier) is a tool designed to track container image updates automatically. It monitors registries on a schedule, detects changes in tracked tags or digests, and sends notifications when new versions are available. This is useful for monitoring upstream base image rebuilds and application releases.

Diun can be deployed as a single executable binary or as a Docker image.

Diun is a tool that watches container images and notifies you when an update is available. It monitors registries for new tags or digest changes, allowing you to track base image updates, application releases, and security rebuilds automatically.

Diun can be deployed as:

• A single executable.
• A Docker image.

It is designed to connect to container platforms and configuration files and send notifications through various supported services.

Diun evaluates configuration in the following order:

1. Configuration file (diun.yml or diun.yaml)
2. Environment variables

If a value is not provided for an option, a default value is applied. If an option has sub-options and only some are specified, the remaining sub-options will use their respective default values.

Note: Setting a top-level environment variable for a provider (e.g., DIUN_PROVIDERS_DOCKER) will enable that provider and reset all its sub-options to their default values.

Diun provides the following capabilities:

• Image Tracking: Watch container images and report changes in tags or digests.
• Filtering: Use include and exclude filters for specific tags when tracking repositories.
• Scheduling: Run checks on a built-in schedule without requiring external cron jobs.
• Multi-Provider Support: Discover images from various sources including:
  • Docker
  • Containerd
  • Kubernetes
  • Swarm
  • Nomad
  • Dockerfile
  • File
• Customization: Override target image OS and architecture.
• Notifications: Send alerts via Gotify, Mail, Slack, Telegram, and other services.
• Monitoring: Integrate with Healthchecks to monitor the status of the Diun watcher itself.
• Logging: Detailed logging for checks, updates, and notification delivery status.

The Containerd provider analyzes containers via the containerd gRPC API socket to extract images and check for registry updates.

To use Diun with Containerd via Docker, you must mount the containerd socket into the Diun container.

Example minimal configuration for a local containerd instance using the default namespace:

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

providers:
  containerd: {}

Example Docker Compose service definition:

services:
  diun:
    image: crazymax/diun:latest
    command: serve
    volumes:
      - "./data:/data"
      - "/run/containerd/containerd.sock:/run/containerd/containerd.sock"
      - "./diun.yml:/diun.yml:ro"
    environment:
      - "TZ=Europe/Paris"
      - "LOG_LEVEL=info"
    restart: always

To resolve too many requests to registry errors (HTTP 429), authenticate against the registry using the regopts settings. If rate limits persist, increase the interval between scans by adjusting the schedule setting (e.g., to every 6 hours).

regopts:
  - name: "docker.io"
    selector: image
    username: foo
    password: bar

Since version 4.17, the CLI has changed. To start Diun with a configuration file, you must now use the serve command instead of passing arguments directly to the diun binary.

Note: This change applies to versions 4.17 and later.

diun serve --config diun.yml

To route registry checks or notification requests through a proxy (like Squid), set the standard environment variables HTTP_PROXY, HTTPS_PROXY, and NO_PROXY in the Diun container.

Note: These settings apply to the Diun process inside the container, not the Docker daemon itself. Use NO_PROXY for local services or private registries that should be contacted directly.

services:
  diun:
    image: crazymax/diun:latest
    environment:
      - "HTTP_PROXY=http://squid.local:3128"
      - "HTTPS_PROXY=http://squid.local:3128"
      - "NO_PROXY=localhost,127.0.0.1,::1"
    # ... other config

You can send Diun notifications to a Microsoft Teams channel using either an incoming webhook URL or a Microsoft Teams Workflows webhook URL.

To configure this, add a teams section under notif in your configuration file. You can specify the webhookURL, the cardType (either messageCard or adaptiveCard), and customize the message using templateBody.

If you are using a webhook URL created via the Teams Workflows app, you must set cardType to adaptiveCard.

notif:
  teams:
    webhookURL: https://outlook.office.com/webhook/ABCD12EFG/HIJK34LMN/01234567890abcdefghij
    cardType: messageCard
    renderFacts: true
    templateBody: |
      Docker tag {{ .Entry.Image }} which you subscribed to through {{ .Entry.Provider }} provider has been released.