Skip to content
πŸ”” Receive notifications when an image is updated on a Docker registry
Branch: master
Clone or download
Latest commit 971a8ba Jun 23, 2019

GitHub release Total downloads Build Status Docker Tag Docker Stars Docker Pulls
Docker Repository on Quay Go Report Code Quality Donate Paypal


Diun πŸ”” is a CLI application written in Go to receive notifications πŸ“₯ when a Docker 🐳 image is updated on a Docker registry. With Go, this app can be used across many platforms 🎲 and architectures. This support includes Linux, FreeBSD, macOS and Windows on architectures like amd64, i386, ARM and others.


  • Allow to watch a full Docker repository and report new tags
  • Include and exclude filters with regular expression for tags
  • Internal cron implementation through go routines
  • Worker pool to parallelize analyses
  • Allow overriding os and architecture when watching
  • Beautiful email report
  • Webhook notification
  • Enhanced logging
  • Timezone can be changed
  • 🐳 Official Docker image available


Diun binaries are available in releases page.

Choose the archive matching the destination platform and extract diun:

$ cd /opt
$ wget -qO- | tar -zxvf - diun

After getting the binary, it can be tested with ./diun --help or moved to a permanent location.

$ ./diun --help
usage: diun --config=CONFIG [<flags>]

Docker image update notifier. More info on

  --help              Show context-sensitive help (also try --help-long and
  --config=CONFIG     Diun configuration file.
  --timezone="UTC"    Timezone assigned to Diun.
  --log-level="info"  Set log level.
  --log-json          Enable JSON logging output.
  --log-caller        Enable to add file:line of the caller.
  --run-startup       Run on startup.
  --docker            Enable Docker mode.
  --version           Show application version.


diun --config=CONFIG [<flags>]

  • --help : Show help text and exit. Optional.
  • --version : Show version and exit. Optional.
  • --config <path> : Diun YAML configuration file. Required. (example: diun.yml).
  • --timezone <timezone> : Timezone assigned to Diun. Optional. (default: UTC).
  • --log-level <level> : Log level output. Optional. (default: info).
  • --log-json : Enable JSON logging output. Optional. (default: false).
  • --log-caller : Enable to add file:line of the caller. Optional. (default: false).
  • --run-startup : Run on startup. Optional. (default: false).


Before running Diun, you must create your first configuration file. Here is a YAML structure example :

  path: diun.db

  workers: 10
  schedule: 0 0 * * * *
  os: linux
  arch: amd64

    enable: false
    host: localhost
    port: 25
    ssl: false
    insecure_skip_verify: false
    enable: false
    method: GET
      Content-Type: application/json
      Authorization: Token123456
    timeout: 10

    username: foo
    password: bar
    timeout: 20
    username: foo2
    password: bar2
    insecure_tls: true

  # Watch latest tag of crazymax/nextcloud image on (DockerHub) with registry ID 'someregistryoptions'.
    registry_id: someregistryoptions
  # Watch 4.0.0 tag of jfrog/artifactory-oss image on (Bintray) with registry ID 'onemore'.
    registry_id: onemore
  # Watch coreos/hyperkube image on (Quay). Assume latest tag.
  # Watch crazymax/swarm-cronjob image and assume regsitry and latest tag.
  # Only include tags matching regexp ^1\.2\..*
    image: crazymax/swarm-cronjob
    watch_repo: true
      - ^1\.2\..*
  # Watch portainer/portainer image on (DockerHub) and assume latest tag
  # Only watch latest 10 tags and include tags matching regexp ^(0|[1-9]\d*)\..*
    watch_repo: true
    max_tags: 10
      - ^(0|[1-9]\d*)\..*
  • db
    • path: Path to Bolt database file where images manifests are stored. Flag --docker force this path to /data/diun.db (default: diun.db).
  • watch
    • workers: Maximum number of workers that will execute tasks concurrently. Optional. (default: 10).
    • schedule: CRON expression to schedule Diun watcher. Optional. (default: 0 0 * * * *).
    • os: OS to use for choosing images. Optional. (default: linux).
    • arch: Architecture to use for choosing images. Optional. (default: amd64).
  • notif
    • mail
      • enable: Enable email reports (default: false).
      • host: SMTP server host (default: localhost). required
      • port: SMTP server port (default: 25). required
      • ssl: SSL defines whether an SSL connection is used. Should be false in most cases since the auth mechanism should use STARTTLS (default: false).
      • insecure_skip_verify: Controls whether a client verifies the server's certificate chain and host name (default: false).
      • username: SMTP username.
      • password: SMTP password.
      • from: Sender email address. required
      • to: Recipient email address. required
    • webhook
      • enable: Enable webhook notification (default: false).
      • endpoint: URL of the HTTP request. required
      • method: HTTP method (default: GET). required
      • headers: Map of additional headers to be sent.
      • timeout: Timeout specifies a time limit for the request to be made. (default: 10).
  • registries: Map of registry options to use with items. Key is the ID and value is a struct with the following fields:
    • username: Registry username.
    • password: Registry password.
    • timeout: Timeout is the maximum amount of time for the TCP connection to establish. 0 means no timeout (default: 10).
    • insecure_tls: Allow contacting docker registry over HTTP, or HTTPS with failed TLS verification (default: false).
  • items: Slice of items to watch with the following fields:
    • image: Docker image to watch using registry/path:tag format. If registry is omitted, will be used and if tag is omitted, latest will be used. required
    • registry_id: Registry ID from registries to use.
    • watch_repo: Watch all tags of this image repository (default: false).
    • max_tags: Maximum number of tags to watch if watch_repo enabled. -1 means all of them (default: 25).
    • include_tags: List of regular expressions to include tags. Can be useful if you enable watch_repo.
    • exclude_tags: List of regular expressions to exclude tags. Can be useful if you enable watch_repo.


Diun provides automatically updated Docker 🐳 images within Docker Hub and Quay. It is possible to always use the latest stable tag or to use another service that handles updating Docker images.

Environment variables can be used within your container :

  • TZ : Timezone assigned
  • LOG_LEVEL : Log level output (default info)
  • LOG_JSON: Enable JSON logging output (default false)
  • LOG_CALLER: Enable to add file:line of the caller (default false)
  • RUN_STARTUP: Run on startup (default false)

Docker compose is the recommended way to run this image. Copy the content of folder .res/compose in /opt/diun/ on your host for example. Edit the compose and config file with your preferences and run the following commands :

docker-compose up -d
docker-compose logs -f

Or use the following command :

$ docker run -d --name diun \
  -e "TZ=Europe/Paris" \
  -e "LOG_LEVEL=info" \
  -e "LOG_JSON=false" \
  -e "RUN_STARTUP=false" \
  -v "$(pwd)/data:/data" \
  -v "$(pwd)/diun.yml:/diun.yml:ro" \


If you choose webhook notification, a HTTP request is sent with a JSON format response that looks like:

  "diun_version": "0.3.0",
  "status": "new",
  "image": "",
  "mime_type": "application/vnd.docker.distribution.manifest.v2+json",
  "digest": "sha256:5913d4b5e8dc15430c2f47f40e43ab2ca7f2b8df5eee5db4d5c42311e08dfb79",
  "created": "2019-01-24T10:26:49.152006005Z",
  "architecture": "amd64",
  "os": "linux"

And here is an email sample if you add mail notification:


  • Watch images inside Dockerfile and Compose files
  • Watch images from Docker daemon
  • Watch starred repo on DockerHub and Quay

How can I help ?

All kinds of contributions are welcome πŸ™Œ!
The most basic way to show your support is to star 🌟 the project, or to raise issues πŸ’¬
But we're not gonna lie to each other, I'd rather you buy me a beer or two 🍻!



MIT. See LICENSE for more details.

You can’t perform that action at this time.