jakowenko/watchtower

•Updated about 5 years ago

Watch Docker containers and check for image updates on Docker Hub

Image

10K+

jakowenko/watchtower repository overview

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

------------------------------------------------
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'

Tag summary

Recent tags

Content type

Image

Digest

Size

112 MB

Last updated

about 5 years ago

docker pull jakowenko/watchtower