Watchtower solves the common problem of how to update running Docker containers when a new image is released. Watchtower automatically “tracks” your containers, polling them periodically for new versions of their images and restarting them to run a new release.
In this article, we’ll show you how to use Watchtower to simplify the management of your container fleet. We’ll also look at the advanced options you can use to customize Watchtower’s behavior.
Placement of the Watchtower
The first step is to launch a Watchtower instance in its own Docker container. Run the following command to download the Watchtower image and create a container:
$ docker run -d --name watchtower \ -v /var/run/docker.sock:/var/run/docker.sock \ containrrr/watchtower
Installed on a Watchtower container with your host’s Docker socket
-v flag. This allows Watchtower to communicate with the host’s Docker daemon instance. This is required so that Watchtower can list and launch containers.
It is possible to use Watchtower with a remote Docker host. Expose that host’s Docker daemon on a TCP port, then start Watchtower with a
DOCKER_HOST environment variable instead of nest binding:
$ docker run -d --name watchtower \ -e DOCKER_HOST="tcp://192.168.0.1:2375" \ containrrr/watchtower
If your Docker host is TLS protected, use Watchtower
--tlsverify mark and place your certificates in the container
$ docker run -d --name watchtower \ -e DOCKER_HOST="tcp://192.168.0.1:2375" \ -e DOCKER_CERT_PATH=/etc/ssl/docker -v ./certs:/etc/ssl/docker containrrr/watchtower --tlsverify
Watchtower is designed to run once per Docker host. When a new Watchtower instance is started, it will clean up all other existing Watchtower containers. You can run multiple instances by assigning them each a unique scope, but this is usually not necessary in most deployments.
Using the Watchtower
Your Watchtower container immediately starts monitoring other containers on your Docker host. It will poll for image updates once every 24 hours and restart your containers when changes occur.
The new container retains the same options as the original it was created from. Port bindings, volume mounts, environment variables and any other settings will be unaffected when changed.
Watchtower is also dependency-aware: when containers are linked together, Watchtower will stop and start them in logical order. Services that depend on a particular container will be stopped before that container is updated, and then restarted once the replacement is available. This ensures that your applications do not encounter errors when updating their dependencies.
SIGTERM signals containers when they need to stop for an update. You can change this signal by labeling your containers. How to go about it
SIGHUP instead of
$ docker run -d --label=com.centurylinklabs.watchtower.stop-signal=SIGHUP my-image
Exceptions and Containers Included
You can customize which containers are monitored using a combination of Watchtower command arguments and Docker tags on your individual containers. Here’s an example of running a container extracted from Watchtower updates using the label:
$ docker run -d --label=com.centurylinklabs.watchtower.enable=false my-image
It is also possible to whitelist containers that should be updated instead of discarding those that should not be updated. start the Watchtower with
--label-enable tick to enable this behavior:
$ docker run -d --name watchtower \ -v /var/run/docker.sock:/var/run/docker.sock \ containrrr/watchtower --label-enable
Now use a label to set some containers as eligible to receive updates:
$ docker run -d --label=com.centurylinklabs.watchtower.enable=true my-image
Life cycle hooks
Watchtower can optionally run scripts inside your containers when special events occur. Four hooks are available:
pre-check– Before Watchtower checks for an update for the container.
pre-update– After an update is detected but before the container is restarted.
post-update– After the update is complete.
post-check– After the container has finished checking for updates.
Hooks are configured using container tags. The tag value must be the path to the executable inside the container image. This will be called every time the hook fires.
Here is a usage example
$ docker run -d --label=com.centurylinklabs.watchtower.lifecycle.pre-update="/backup.sh --create" my-image
Other hooks are configured similarly by substituting their names in the label.
Notifications and Monitoring
Watchtower can send you notifications via email, Slack, Microsoft Teams, Gotify, and Shoutrrr when container updates are available. Each of these delivery mechanisms must be configured separately by setting environment variables in your Watchtower container.
Here’s a basic example using Gmail:
$ docker run -d --name watchtower \ -e WATCHTOWER_NOTIFICATIONS=email -e [email protected] -e [email protected] -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.gmail.com -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587 -e [email protected] -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=your_gmail_app_password -v /var/run/docker.sock:/var/run/docker.sock \ containrrr/watchtower
Watchtower also supports an operational mode where it checks for container updates without applying them. You can use this to be notified when updates are available, then manually restart your containers at the appropriate time.
activate this mode with
$ docker run -d --name watchtower \ -v /var/run/docker.sock:/var/run/docker.sock \ containrrr/watchtower --monitor-only
There is also a label that can be installed on individual containers to switch to monitoring mode:
$ docker run -d --label=com.centurylinklabs.watchtower.monitor-only=true my-image
Changing the Refresh Request Interval
The Watchtower checks for new images every 24 hours. This interval can be changed
--interval flag or
WATCHTOWER_POLL_INTERVAL environment variable. It accepts the value in seconds.
# Update every hour $ docker run -d --name watchtower \ -e WATCHTOWER_POLL_INTERVAL=3600 -v /var/run/docker.sock:/var/run/docker.sock \ containrrr/watchtower
Alternatively, you can set a fixed polling schedule using the cron syntax. It is accepted as such
--schedule flag or
WATCHTOWER_SCHEDULE environment variable.
# Update every five minutes $ docker run -d --name watchtower \ -e WATCHTOWER_SCHEDULE="*/5 * * * *" -v /var/run/docker.sock:/var/run/docker.sock \ containrrr/watchtower
Cleaning Out Old Photos
Watchtower leaves the old version of the container images on your host after the new one is pulled. appointment
--cleanup flag or
WATCHTOWER_CLEANUP environment variable will delete old images after update. This can drain a significant amount of disk space over time.
$ docker run -d --name watchtower \ -e WATCHTOWER_CLEANUP=true -v /var/run/docker.sock:/var/run/docker.sock \ containrrr/watchtower
Runs On Demand
Watchtower is designed to run as a long-lived daemon that constantly monitors containers for updates. Sometimes you may want to manually check for new required images. You can do with this
--run-once team flag:
$ docker run --rm \ -v /var/run/docker.sock:/var/run/docker.sock \ containrrr/watchtower --run-once
This will make a single update attempt for all your running containers. The Watchtower container will then stop and be removed.
Use of Private Registries
The Watchtower requires authentication details to verify that images in personal registries are updated. One way to provide them is to install Docker
config.json to the file
/config.json In your Watchtower container:
$ docker run -d --name watchtower \ -v $HOME:/.docker/config.json:/config.json -v /var/run/docker.sock:/var/run/docker.sock \ containrrr/watchtower
There is one caveat to this approach: updates
config.json will not necessarily be reflected inside the container on your host. commands like
docker login actually modify the file instead of editing it directly. This creates a new inode by breaking the Docker binding assembly.
Another way to submit registry information to the Watchtower is through it
REPO_PASS variables. It will log in as the specified user before attempting to capture your images.
$ docker run -d --name watchtower \ -e REPO_USER=demo-user -e REPO_PASS=users-password -v /var/run/docker.sock:/var/run/docker.sock \ containrrr/watchtower
Watchtower allows you to automate Docker container updates when new images are pushed to the registry. It is a highly customizable system that supports container blacklists and whitelists, advanced scheduling with cron syntax, and notifications delivered to several popular providers.
Optional configuration settings expose additional functionality such as support for restarts, updates of restarted and suspended containers, and exposing metrics that give you another way to visualize update activity. This makes Watchtower a good choice for managing a dense set of Docker containers.