Skip to content

jakowenko/watchtower

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

NPM Version NPM Downloads Docker Pulls

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'