diun

README

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.

• Features
• Download
• Usage
• Configuration
  • db
  • watch
  • notif
  • regopts
  • image
• Docker
• Notifications
• TODO
• How can I help ?
• License

Features

• 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 image os and architecture
• Beautiful email report
• Webhook notification
• Enhanced logging
• Timezone can be changed
• 🐳 Official Docker image available

Download

Diun binaries are available in releases page.

Choose the archive matching the destination platform and extract diun:

$ cd /opt
$ wget -qO- https://github.com/crazy-max/diun/releases/download/v1.1.0/diun_1.1.0_linux_x86_64.tar.gz | 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 https://github.com/crazy-max/diun

Flags:
  --help              Show context-sensitive help (also try --help-long and
                      --help-man).
  --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.
  --docker            Enable Docker mode.
  --version           Show application version.

Usage

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).

Configuration

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

db:
  path: diun.db

watch:
  workers: 10
  schedule: "0 0 * * * *"

notif:
  mail:
    enable: false
    host: localhost
    port: 25
    ssl: false
    insecure_skip_verify: false
    username:
    password:
    from:
    to:
  webhook:
    enable: false
    endpoint: http://webhook.foo.com/sd54qad89azd5a
    method: GET
    headers:
      Content-Type: application/json
      Authorization: Token123456
    timeout: 10

regopts:
  someregistryoptions:
    username: foo
    password: bar
    timeout: 20
  onemore:
    username: foo2
    password: bar2
    insecure_tls: true

image:
  # Watch latest tag of crazymax/nextcloud image on docker.io (DockerHub) with registry ID 'someregistryoptions'.
  - name: docker.io/crazymax/nextcloud:latest
    regopts_id: someregistryoptions
  # Watch 4.0.0 tag of jfrog/artifactory-oss image on frog-docker-reg2.bintray.io (Bintray) with registry ID 'onemore'.
  - name: jfrog-docker-reg2.bintray.io/jfrog/artifactory-oss:4.0.0
    regopts_id: onemore
  # Watch coreos/hyperkube image on quay.io (Quay) and assume latest tag.
  - name: quay.io/coreos/hyperkube
  # Watch crazymax/swarm-cronjob image and assume docker.io registry and latest tag.
  # Only include tags matching regexp ^1\.2\..*
  - name: crazymax/swarm-cronjob
    watch_repo: true
    include_tags:
      - ^1\.2\..*
  # Watch portainer/portainer image on docker.io (DockerHub) and assume latest tag
  # Only watch latest 10 tags and include tags matching regexp ^(0|[1-9]\d*)\..*
  - name: docker.io/portainer/portainer
    watch_repo: true
    max_tags: 10
    include_tags:
      - ^(0|[1-9]\d*)\..*
  # Watch alpine image (library) and assume docker.io registry and latest tag.
  # Only check linux/arm64v8 image
  - name: alpine
    watch_repo: true
    os: linux
    arch: arm64v8

db

• 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

• 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 * * * *).

notif

• 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).

regopts

• regopts: Map of registry options to use with images. 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).

image

• image: Slice of image to watch with the following fields:
  • name: Docker image name to watch using registry/path:tag format. If registry is omitted, docker.io will be used and if tag is omitted, latest will be used. required
  • os: OS to use. Optional. (default: linux).
  • arch: Architecture to use. Optional. (default: amd64).
  • regopts_id: Registry options ID from regopts 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. 0 means all of them (default: 0).
  • 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.

Docker

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)

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" \
  -v "$(pwd)/data:/data" \
  -v "$(pwd)/diun.yml:/diun.yml:ro" \
  crazymax/diun:latest

Notifications

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": "docker.io/crazymax/swarm-cronjob:0.2.1",
  "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:

TODO

• 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 🍻!

License

MIT. See LICENSE for more details.