Watchtower Docker Compose – Auto Update Docker containers

Docker is a popular tool for building, packaging, and deploying containerized applications. Containers provide a lightweight and portable way to run applications, but they need to be frequently updated to stay secure and up-to-date. Updating containers manually can be time-consuming and tedious, but with Watchtower, you can automate updating Docker containers.

What is Watchtower Container?

Watchtower is an open-source tool that monitors running Docker container instances and manages the operation to automatically update them from Docker hub or your own image registry to the latest available version of the image than originally started. You can load it on your Docker host, running Linux.

On a set schedule, it enumerates an existing container image and checks for a newer version of the Docker image using the Docker API than the version deployed initially. Watchtower runs on any Docker host along with your other running containers.

Containerized app

Watchtower is a containerized application and can be run alongside other Docker containers as a Watchtower instance. 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.

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

By automating the process of updating Docker containers and gracefully shut down the running version of containers, Watchtower can save time and effort and help keep your containers up-to-date and secure.

However, it’s important to use caution when automating updates to ensure that updates do not introduce issues or vulnerabilities into your environment.

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/watchtower

This 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/watchtower

Using 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" 
    image: containrrr/watchtower
    container_name: watchtower 
    restart: always 
      WATCHTOWER_SCHEDULE: "0 0 1 * * *" 
      TZ: America/Chicago 
      WATCHTOWER_DEBUG: "true"      
      WATCHTOWER_NOTIFICATION_EMAIL_TO: "[email protected]" 
      # you have to use a network alias here, if you use your own certificate 
      - /var/run/docker.sock:/var/run/docker.sock

In 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

In this example, we use the –registry-auth argument to supply the username and password for the private Docker registry at 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.

Watchtower can be used with Docker, Docker Compose, and other container orchestration systems. With Watchtower and these systems, you can easily manage your containerized applications and keep them up-to-date with the latest images.

However, it’s essential to test automatic updates properly and have monitoring in place to ensure that updates do not introduce issues or vulnerabilities into your environment. Test updates in a non-production environment before deploying them to production. Additionally, you should consider using a private Docker registry for increased security.

With Watchtower and other tools, managing Docker containers can become automated and streamlined. Automating the process of updating Docker containers can save time and effort, and Watchtower is a great tool to help with this process.

Subscribe to VirtualizationHowto via Email 🔔

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

Brandon Lee

Brandon Lee is the Senior Writer, Engineer and owner at and has over two decades of experience in Information Technology. Having worked for numerous Fortune 500 companies as well as in various industries, Brandon has extensive experience in various IT segments and is a strong advocate for open source technologies. Brandon holds many industry certifications, loves the outdoors and spending time with family.

Related Articles

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.