Watchtower Docker Compose – Auto Update Docker containers
Part of the struggle with running Docker containers is keeping them updated. You can easily have dozens, hundreds, or more containers running various applications. Keeping these all updated by hand can be difficult. But with Watchtower, you can automate updating Docker containers which takes a huge load off the admin in keeping apps updated.
What is Watchtower Container?
Watchtower is an open-source tool that monitors running Docker containers. It manages automatically updating your container updates by looking at the registry URL for the container on Docker hub or your own image registry. If it sees a new version of your container image it will update these to the latest available version of the image than originally started. You can load it on your Docker host, running Linux.
Below, you can see I have an Ubuntu Server 22.04 installation.
On a set schedule, it queries your existing container images and checks for a newer version of the Docker image using the Docker API. It will pull any images newer than the version the container was deployed with. Watchtower runs on any Docker host along with your other running containers.
Containerized app
Watchtower itself is a containerized application. It can be run alongside other Docker containers. When Watchtower detects a new version of a watched image, it pulls the new image from the registry and replaces the containerized app with a new one based on the new image and it also uses the container’s current configuration with the config file. So, you don’t have to worry about losing the options your container was deployed with.
Watchtower can also remove the old container and any unused images to keep your Docker host clean.
As long as the container filesystem is persistent on disk for your critical data, the updated containerized app attaches to the existing data without the command argument changing and using the host’s docker config file.
Automates updates
This process essentially creates a way to have automated updates of your containers. The process of updating Docker containers and gracefully shutting down the running version of containers is handled by Watchtower. This saves tons of time and effort and helps keep your containers up-to-date and secure.
Watchtower is an excellent tool for teams that manage many Docker containers or containerized app or have a complex deployment with multiple containers and pulling images with the latest version during the update process.
It can be used with Docker, Docker Compose, Kubernetes, and other container orchestration systems to manage containerized applications and keep them up-to-date.
Installing Watchtower
To install Watchtower, you can run the following command:
docker run -d --name watchtower -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtowerThis command will start a new ” watchtower ” container to monitor all running containers on your Docker host and update them when a new image is available. The /var/run/docker.sock volume mapping allows Watchtower to communicate with the Docker daemon (Docker socket) and monitor changes in the running containers. Other than this, there are no Watchtower volumes needed.
Configuring Watchtower
After installing Watchtower, you need to configure it to monitor the Docker containers. There are several ways to configure Watchtower, including environment variables and command-line arguments. In this tutorial, we will use environment variables to configure Watchtower.
Watchtower command arguments
To configure Watchtower, you can set the following environment variables:
WATCHTOWER_CLEANUP: This variable tells Watchtower to remove the old image after updating a container. We recommend setting this to true to keep your Docker host clean. (1)
WATCHTOWER_LABEL_ENABLE: This variable tells Watchtower to only update containers that have a specific label. By default, Watchtower updates all running containers. However, if you have some containers that you do not want to update, you can set a label on them and only update the containers with that label. (2-5)
WATCHTOWER_LABEL_FILTER: This variable specifies the label to use as a filter for containers. For example, if you set this to com.example.autoupdate=true, Watchtower will only update containers that have the label com.example.autoupdate=true. (2-5)
WATCHTOWER_POLL_INTERVAL: This variable sets the interval in seconds for how often Watchtower checks for updates. The default value is 300 seconds (5 minutes). You can change this interval by setting the variable to a different value. (2-5)
WATCHTOWER_NOTIFICATIONS – with this you can set the SMTP server or other notification platform you want to use.
To set these environment variables, you can use the following command and Watchtower code:
docker run -d --name watchtower -e WATCHTOWER_CLEANUP=true -e WATCHTOWER_LABEL_ENABLE=true -e WATCHTOWER_LABEL_FILTER=com.example.autoupdate=true -e WATCHTOWER_POLL_INTERVAL=600 -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtowerUsing Watchtower
Once Watchtower is configured, it will start monitoring the running Docker containers and updating them when a new image is available. When Watchtower detects a new version of a watched image, it pulls the new image from the image registry and replaces the running container with a new one based on the new image.
Watchtower can also remove the old container and any unused images to keep your Docker host clean.
Manually stopped or restarted containers
Watchtower will not update containers that have been manually stopped or restarted. If you manually stop a container, you will need to start it again to trigger an update.
You can use the –restart always command argument when creating or updating your containers to make sure the containers automatically restart after a failure or a host restart. (1/4-9)
Watchtower Docker compose file
You can include the Watchtower container and its configuration in the docker-compose.yml file to use Watchtower Docker Compose. Here is an example of a complete Docker compose file for Watchtower container:
version: "3"
services:
watchtower:
image: containrrr/watchtower
container_name: watchtower
restart: always
environment:
WATCHTOWER_SCHEDULE: "0 0 1 * * *"
TZ: America/Chicago
WATCHTOWER_CLEANUP: "true"
WATCHTOWER_DEBUG: "true"
WATCHTOWER_NOTIFICATIONS: "email"
WATCHTOWER_NOTIFICATION_EMAIL_FROM: "[email protected]"
WATCHTOWER_NOTIFICATION_EMAIL_TO: "[email protected]"
# you have to use a network alias here, if you use your own certificate
WATCHTOWER_NOTIFICATION_EMAIL_SERVER: "10.1.149.19"
WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT: "8025"
WATCHTOWER_NOTIFICATION_EMAIL_DELAY: 2
volumes:
- /var/run/docker.sock:/var/run/docker.sockIn this example, the Watchtower container is added as a new service in the Docker Compose file. The watchtower service has the same options as when using the docker run command, with the addition of the restart: always option, which ensures that Watchtower is always running.
Using Docker Compose, you can easily create and manage multi-container applications and other containers and keep them up-to-date with Watchtower. If you have a more complex deployment, you can use Kubernetes or other container orchestration systems to manage your containers.
Private Docker Registries
If you use a private Docker registry, you must supply the private repo registry authentication credentials to Watchtower. When running the Watchtower container, you can use the –registry-auth command argument to supply registry authentication credentials. Note the below example:
docker run -d --name watchtower --restart always -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower --cleanup --debug --interval 60 --schedule "0 0 4 *" --label-enable --label-filter com.example.autoupdate=true --registry-auth username:password registry.example.comIn this example, we use the –registry-auth argument to supply the username and password for the private Docker registry at registry.example.com to pull images with the most recent version when you commit a new image.
Other solutions to update Docker containers
There are other ways to update your Docker containers. You can use free and open service solutions like Portainer to update your containers.
Watchtower Docker Container FAQs
What is Watchtower Docker container? The Watchtower Docker container solution is a special container that watches other containers running in your environment and pulls the most recent images at specified intervals.
What does Watchtower allow you to do? It allows you to automate the process of updating your Docker containers so these are always running the latest images.
How does Watchtower automatically restart and update your containers? It watches the Docker containers running on your Docker host. At the specified interval, it checks for the latest image and pulls down the latest image.
Do you have to have Watchtower to update your containers? No you can update your containers by pulling the latest container image and restarting the container.
Can you update private repository containers? Yes, Watchtower has a parameter for private repository credentials. This feature allows logging in and pulling down the latest images from a private repository.
Is there a way to skip certain containers? Yes you can direct Watchtower to skip specific containers.
Can you clean up old container images? Watchtower has a clean option to delete old container images.
Can you send notifications? Watchtower supports several modern notifications and also supports legacy email notifications.
Wrapping up
Watchtower is an excellent tool for automating and updating Docker containers. With Watchtower, you can keep your containers up-to-date and secure without manual updates. By following the steps outlined in this tutorial, you can easily install and configure Watchtower to start auto-updating your Docker containers.
