Photo by Alan on Unsplash

Photo by Alan on Unsplash

Updating Docker containers with Watchtower

Elevated View

Article from ADMIN 65/2021
Automatically update software in the Docker universe with Watchtower.

Deploying microservices with Docker is relatively easy. With very little overhead, you can complete complex software installations and offer services in your company. However, controlling an infrastructure that has grown very quickly can often be far more time-consuming than the actual deployment. The progressive use of microservices, and with it the need to provision individually customized ecosystems within containers, leads to a confusing update jungle. If something goes wrong in the process, an unreachable service is in many ways less critical than a service that is vulnerable to attackers. Possible downtime is then supplemented by close monitoring and fallback strategies.

Regardless of how you manage your Docker containers – whether directly with Docker itself, with Docker Compose, or with one of the many other tools – you will want a working backup solution, and you will want to ensure that software updates are automated to the greatest extent possible. In this article, I look at Watchtower as an option for automatically updating your Docker containers.

Launching Watchtower

The initial setup for Watchtower is roughly equivalent in scope and complexity to changing a light bulb. If all tools are ready and the Docker daemon is running, you can launch Watchtower with:

docker run -d --name watchtower -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower

This command sends the launched container directly into the background with -d (detach). You can freely select the name by specifying --name and use the -v option to include areas of the filesystem as a volume in the container's process group. The command includes the Docker daemon's communication socket because that is how Watchtower communicates and transmits its commands. The last argument of the command line passes in the Watchtower path in the Docker Hub registry [1].

Once started, Watchtower takes direct control and monitors the availability of new image versions for all running Docker containers. If a new version is available, Watchtower downloads it and restarts the affected containers. All the parameters of the containers (i.e., the parameters you specified with docker run) are taken into account and passed in accordingly on restart. In this way, mounted volumes and shared ports persist despite updates.

Please note that Watchtower also takes into account tags that you attach to the images. The best known tag is probably latest , which lets the creator of an image publish the fact that the image is the latest available version. However, when updating from latest , Watchtower also jumps to new major release versions. If you have a piece of software that is version 3.8.12, you might see version 4.0.1 start up as an updated image, which might not always be what you want.

If the software you use supports extensions through a plugin system, for example, these extensions often are not immediately compatible with the next major release. Therefore, a good practice among creators of Docker images is to assign tags that are as complete as possible. Version 3.8.12 is then assigned the tags latest , 3 , 3.8 , and 3.8.12 at the time of release. Therefore, as an administrator, you can define your desired version and the update strategy for Watchtower. If you start an image with :3 , you will get version 3.9, 3.10, and so forth in the future. An image that starts :3.8 will give you 3.8.13 and so on, whereas :3.8.12 will mean you do not receive any updates.

Selectively Distributing Updates

Probably the most important feature that developers can include with a Docker image is the update and migration capability of the application it contains. Importing new container images, then, also results in automatically adjusted startup times in all necessary configuration and database settings of the provided software. Therefore, it depends on the container's entry point, configured as a RUN command within the Dockerfile, whether a container image can be updated easily. Most official images have this capability.

You might want to have Watchtower automatically update only selected containers. Docker lets you pass in additional arguments to a container's entry point with the docker run command. Watchtower uses this ability to pass in container names and thus define which containers should be updated. To include only the containers for Nextcloud, Elasticsearch, and Mailman, extend the command as follows:

docker run -d --name watchtower -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower Nextcloud Elasticsearch Mailman

Keep in mind that this selection also removes Watchtower itself from the list of automatically updated containers. If you want the tool to update itself, you need to specify it.

Another way to select containers is with container labels, which you assign to a container at startup time with the -l option. One advantage of this method is that you can also select containers that you create after Watchtower has been launched; then you tell Watchtower only to update containers with the corresponding label by the environment variable


during the docker run command.

To add the appropriate label to all other containers that you start before or after Watchtower, use:

-l com.centurylinklabs.watchtower.enable="true"

Again, if you want Watchtower to update itself, you need to start the container with the appropriate label.

Creating Schedules and Trial Runs

If you want to manage the times at which Watchtower checks the containers, you can use the WATCHTOWER_SCHEDULE environment variable by filling the variable with a string in the extended Cron syntax of the Go programming language, on which Watchtower is essentially based [2], corresponding to the known Cron syntax of your Unix system, with a field for seconds at the front. If you want Watchtower to start working every six hours, add the argument

-e WATCHTOWER_SCHEDULE="0 0 */6 * * *"

to the docker run command.

As discussed earlier, if you use containers for which automatic updates are difficult or unreliable, you can also configure Watchtower simply to check the container images for updates and notify you when they are available. Watchtower supports various approaches, such as email or instant messaging with Slack, Microsoft Teams, and other services.

To enable email notification, you first need to protect the corresponding container against automatic updates by assigning a label specifying

-l com.centurylinklabs.watchtower.monitor-only="true"

when creating the container. Extend the Watchtower environment as shown in Listing 1 to include the environment variables for configuring an email gateway. In this way, you can permanently keep track, and you can manually trigger any updates that become available.

Listing 1

Email Gateway


Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy ADMIN Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

comments powered by Disqus
Subscribe to our ADMIN Newsletters
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs

Support Our Work

ADMIN content is made possible with support from readers like you. Please consider contributing when you've found an article to be beneficial.

Learn More”>


		<div class=