Watchtower

Watch Docker containers and check for image updates on Docker Hub. Watchtower can be used to monitor for updates or automatically update existing containers with the new image.

This project was inspired by https://github.com/containrrr/watchtower and is not affiliated with it.

------------------------------------------------
watching 10 containers @ 06/09/2020 01:02:01 EDT
------------------------------------------------
2 updates found
grafana/grafana:latest | 3 hours ago
portainer/portainer:latest | 15 minutes ago
------------------------------------------------
downloading 2 images
grafana/grafana:latest
portainer/portainer:latest
downloads complete in 13.28 seconds
------------------------------------------------
recreating 2 containers
grafana
portainer
recreations complete in 4.57 seconds
------------------------------------------------
pruning images & volumes
2 images | 54.50 MB
0 volumes
pruning complete in 1.02 seconds
-----------------------------------------------
run complete in 19.46 seconds

Install

Node.js npm install @jakowenko/watchtower

Docker docker pull jakowenko/watchtower

Usage

Node.js

const watchtower = require('@jakowenko/watchtower');

watchtower.run();

Docker

docker run -d \
  --name=watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  jakowenko/watchtower

version: '3.7'

services:
  watchtower:
    container_name: watchtower
    image: jakowenko/watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro

How are updates detected?

There are currently two ways Watchtower checks for image updates.

• If the last_updated value on Docker Hub is newer than your containers createdAt value.
• If the last_updated value on Docker Hub changes while Watchtower is running.

/* Docker Hub API v2 Sample Response Snippet */
{
  "last_updated": "2020-05-28T13:50:21.956701Z",
  "last_updater_username": "jakowenko",
  "name": "latest",
  "images": [
    {
      "architecture": "amd64",
      "features": "",
      "variant": null,
      "os": "linux",
      "os_features": "",
      "os_version": null,
      "size": 380405997
    }
  ],
  "repository": 9138104,
  "full_size": 380405997,
  "v2": true
}

Setting a valid NOTIFY_TYPE will result in a notification if either of the above conditions are met.

If NOTIFY_TYPE is set to http then notifications will be POSTed to NOTIFY_HTTP_URL with the following payload:

{
  "title": "Watchtower",
  "text": "Sample notification message"
}

Options

| Name | Default | Description | | ----------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------ | | WATCH_ALL | true | Watch all running containers | | AUTO_UPDATE | false | When an update is detected, Watchtower will pull the newest image and recreate the container with the same configuration | | AUTO_UPDATE_WATCHTOWER | true | Creates a helper container to aid in updating the Watchtower container | | UPDATE_ON_START | false | Automatically pull new images and recreate all containers when Watchtower starts | | TIMER | 30 | Time in minutes before rechecking containers. If set to 0, Watchtower will only run once | | DB_MEMORY | true | Whether to store the database in memory or on disk | | PRUNE_IMAGES | false | Remove all unused images | | PRUNE_VOLUMES | false | Remove all unused local volumes | | TZ | UTC | Timezone used in logs | | TIME_FORMAT | MM/DD/YYYY hh:mm:ss | Format of time used in logging and notifications | | TELEMETRY | true | Pass telemetry data to help improve Watchtower | | EXTRA_IMAGES | | Comma separated list of Docker Hub images to watch (cdr/code-server, esphome/esphome:dev) | | NOTIFY_TYPE | | Type of notification: http, email | | NOTIFY_SUBJECT | Watchtower | Subject value passed in notification | | NOTIFY_HTTP_URL | | URL POST request is sent to for notifications | | NOTIFY_EMAIL_HOST | | SMTP server to send emails | | NOTIFY_EMAIL_PORT | 587 | Port used to connect to the SMTP server | | NOTIFY_EMAIL_IGNORE_TLS | false | Ignore TLS with the SMTP server | | NOTIFY_EMAIL_USERNAME | | Username to authenticate with the SMTP server | | NOTIFY_EMAIL_PASSWORD | | Password to authenticate with the SMTP server | | NOTIFY_EMAIL_FROM_NAME | Notify | Sender name for the email notifications | | NOTIFY_EMAIL_TO | | Email address to which notifications will be sent |

Option Usage

Options are passed to Watchtower with environment variables or by using a .env file in the root directory of your project.

Node.js

const watchtower = require('@jakowenko/watchtower');

watchtower.run({
  TZ: 'America/Detroit',
  PRUNE_IMAGES: true,
  PRUNE_VOLUMES: true,
});

Docker

docker run -d \
  --name=watchtower \
  -e TZ=America/Detroit \
  -e PRUNE_IMAGES=true \
  -e PRUNE_VOLUMES=true \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  jakowenko/watchtower

version: '3.7'

services:
  watchtower:
    container_name: watchtower
    image: jakowenko/watchtower
    restart: unless-stopped
    environment:
      TZ: America/Detroit
      PRUNE_IMAGES: 'true'
      PRUNE_VOLUMES: 'true'
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro

Labels

Labels can used to:

• Include or exclude specific containers from being watched
• Automatically pull the newest image and recreate the container when Watchtower starts

Enable

version: '3.7'

services:
  example:
    image: example/example-watch
    labels:
      - 'watchtower.enable=true'

Disable

version: '3.7'

services:
  example:
    image: example/example-dont-watch
    labels:
      - 'watchtower.enable=false'

Update on Start

version: '3.7'

services:
  example:
    image: example/example-watch
    labels:
      - 'watchtower.update-on-start=true'