crazy-max_diun/README.md

About

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

• 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
• Allow overriding os and architecture when watching
• 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/v0.3.1/diun_0.3.1_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.
  --run-startup       Run on startup.
  --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).
• --run-startup : Run on startup. 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:
  schedule: 0 0 * * * *
  os: linux
  arch: amd64

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

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

items:
  -
    image: docker.io/crazymax/nextcloud:latest
    registry_id: someregistryoptions
  -
    image: jfrog-docker-reg2.bintray.io/jfrog/artifactory-oss:4.0.0
    registry_id: onemore
  -
    image: quay.io/coreos/hyperkube
  -
    image: crazymax/swarm-cronjob
    watch_repo: true
    include_tags:
      - ^1.2.*

• 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
  • 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, docker.io will be used. 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).
  • 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)
• 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" \
  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
• Fetch image size

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.