Docker

Get Started with Docker - Part 6: Watchtower : How to Update Docker Containers and Images The Easy Way

Repro Dev

Mar 19, 2024 • 6 min read

Logos Property of https://containrrr.dev/watchtower & Docker https://www.docker.com

At this point in the Get Started with Docker series you should have a few useful services running in containers.

The flexibility of using Docker Compose files or Docker Run commands lets you easily deploy these using either Portainer or the Docker Command Line Interface (Docker CLI). You can set and forget them for the most part and just reap the benefits of your self hosted services.

But there's one thing that we can't avoid and that's those pesky application updates.

You can do these manually by using the Docker Command line to download the new docker image, stop, remove and then redeploy your containers. This can become quite a boring and manual task depending on the number of containers you're running. It can also be a minefield depending on how you deployed them in the first place with custom environment options or volume bind options.

via GIPHY

Instead of doing all of that, we can use a handy Docker container.

This will check for updates, update, stop and remove all of the Docker images and containers for us. The Docker container we'll be using is Watchtower.

We'll be

Looking at What Watchtower is
Going to the project page for Portainer for our build and install instructions
SSH into the host machine where Docker is installed
Spin up and deploy our Watchtower Docker Container
Updating only one or more specific containers

What is Watchtower?

Watchtower is a way to automate the process of updating the Docker base images of running Docker containers.

By default, Watchtower will run in the background, checking the current Docker base images of all containers against the latest version on the Docker Image registry every 5 minutes.

It will then download all the latest images locally and gracefully shut down all the corresponding containers that need the update.

Finally, Watchtower will start back up all of the containers it shut down using the new Docker base image. Most importantly they will be started with all the settings they were running before they shut down, automatically.

Using command line arguments, this microservice can be set to exclude certain containers that are mission critical and can be ran once without running in the background.

Watchtower Project Page

The Watchtower GitHub page has the most up to date information on this project.

Watchtower has been released under Apache 2.0 License which allows the code to be reused as part of pretty much any project even if it's closed source and proprietary.

There is also a bigger breakdown of the features, development and some further information linked below on the developer's online Knowledgebase.

Watchtower

logo

Let's get started with Watchtower

In this guide, we're going to run Watchtower using the just once option instead of letting it check every 5 minutes. This way you can pick a maintenance window and time each week to run it.

We're going to be using the Raspberry Pi from earlier which currently had Whoogle, Pi-hole and Nginx Proxy Manager.

❗

Please Note: Once run you'll have a brief period of downtime of a few seconds to minutes for the containers that are shut being upgraded. Make sure you know this before running this against containers that are mission critical.

SSH into your Docker install

Run the Docker Run command to run Watchtower once

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

Wait for Watchtower to start running and the logs to start outputting

Go and make a coffee as Watchtower does it's magic

Enjoy your newly updated containers with updated base images

Command Line Arguments

When you update all of the running containers on a Docker host this could actually be quite disruptive depending on the services you are running.

You may also want to run this on remote hosts if you want to automate things further.

Here are a few useful examples of how to use Command Line Arguments with Watchtower and the Docker Run command

Updating a single container

By adding the name of the containers you want to target as a command line argument only the named container will be updated by Watchtower

The example below would only update whoogle

docker run --rm --name watchtower -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower --run-once whoogle

Updating multiple named containers

By adding the name of the more than one container as a command line argument with spaces in between them will make sure that only these are updated by Watchtower ignoring all the others.

This example would only update nginx-proxy-manager and whoogle

docker run --rm --name watchtower -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower --run-once nginx-proxy-manager whoogle

Updating Remote Hosts

If you want to update the containers and images on a remote host then you can do this by using one of the 2 commands below.

Using this method may not always work and you may need to do some network troubleshooting if you run into trouble which is outside the scope of this guide.

To get this working, you will need to have Docker installed on the machine you're using to be able to send the Docker commands to the remote host.

In this example, we'll use the ip address 192.168.0.23 as our remote host. We'll run the command on the other machine to run this.

The below 2 will check containers on the remote host every 5 minutes as default using the default exposed port of 2375 for the Docker Daemon.

I've also changed the name of the container to make sure that this isn't the same as the normal Watchtower container if you're already running it.

docker run -d \
  --name watchtowerremote \
  containrrr/watchtower --host "tcp://192.168.0.23:2375"

docker run -d \
  --name watchtowerremote \
  -e DOCKER_HOST="tcp://192.168.0.23:2375" \
  containrrr/watchtower

The 2 commands below would do this as a Run Once similar to the way that they are done in the rest of the guide.

docker run --rm \
  --name watchtowerremote \
  containrrr/watchtower --host "tcp://192.168.0.23:2375"

docker run --rm \
  --name watchtowerremote \
  -e DOCKER_HOST="tcp://192.168.0.23:2375" \
  containrrr/watchtower

Congratulations, you've now taken another step into the world of Docker by automating one of the most common parts of a Docker set up.

If you're a bit more confident you can run this in the background on a set time interval to update your containers but my advice would be to set aside some time each week to do this manually to start with. Watchtower will make process a lot easier.

via GIPHY

Don't forget to explore the rest of our website as we build out more content. Stay tuned for more tutorials, tips, and tricks to help you make tech work for you.

If you want to stay up-to-date with regular updates, make sure to subscribe to our free mailing list.