Introduction to Watchtower
So you’ve installed docker, and have a few self-hosted application containers up and running. Now, what happens when you need to update those containers? You stop the running container, pull the new image, and start the new container with all of the same environmental variables.
Typically, this is not a big deal, but what if you have 20 containers running? Now, the simple task up updating your applications is going to take a lot of time. That’s where Watchtower comes in.
What is Watchtower?
Watchtower is an application within a docker container that watches for updates for all of the running containers on a system. If an update is available for any of the containers, then Watchtower will restart that container with the new image using the same parameters as the previously running image.
Simple Docker Run Command
Running Watchtower for most users is simple, all you need to do is run the following command in terminal to start the application:
docker run -d \ --name watchtower \ -v /var/run/docker.sock:/var/run/docker.sock \ containrrr/watchtower
This command creates a container named watchtower and connects to the docker socket on the host using the Watchtower image from the Docker Hub.
Once Watchtower is running, it will begin to scan all running applications for updates and will restart those containers with the new image.
Additional Variables
Watchtower has plenty of options to make it run in any way you want. You can add any of the below variables to your docker run code to configure Watchtower. These are only some commonly used options. All of the variables are available for review at the Watchtower documentation page.
| Variable | Description |
-e TZ=America/New_York | Change your time zone with the correct time zone from the TZ Database. |
-e WATCHTOWER_CLEANUP=true | This option will delete the old images from your system when new images are downloaded. This prevents old images from building up and taking space on your system. |
-e WATCHTOWER_DEBUG=true | This option will enable verbose logging in the Watchtower log. |
-e WATCHTOWER_INCLUDE_STOPPED=true | Adding this variable will allow Watchtower to monitor and upgrade stopped containers in addition to running containers. |
-e WATCHTOWER_REVIVE_STOPPED=true | This variable will take those stopped containers in the previous variable and start them once they are upgraded. |
-e WATCHTOWER_POLL_INTERVAL=300 | This variable determines how often Watchtower will check for updates. Change 300 to your desired polling value in seconds. |
-e WATCHTOWER_LABEL_ENABLE=true | This variable configures Watchtower to only check containers that have the following label set to true: com.centurylinklabs.watchtower.enable |
-e WATCHTOWER_MONITOR_ONLY=true | Use this to configure Watchtower to only monitor for updates. In the mode, Watchtower will not pull new images or update the containers. |
Advanced Docker Run Comand
Below is an example of a more advanced docker run command that can be used. The below command will start Watchtower in the Eastern Timezone. Also, it will delete old docker images as new ones are downloaded. It activates verbose logging. Watchtower is also configured to include stopped containers and revive those containers if they are updated. Finally, it is set to check for upgrades once per hour.
docker run -d \ --name Watchtower \ -e TZ=America/New_York \ -e WATCHTOWER_CLEANUP=true \ -e WATCHTOWER_DEBUG=true \ -e WATCHTOWER_INCLUDE_STOPPED=true \ -e WATCHTOWER_REVIVE_STOPPED=true \ -e WATCHTOWER_POLL_INTERVAL=3600 \ -v /var/run/docker.sock:/var/run/docker.sock \ containrrr/watchtower
Success
Now container upgrades are automated. If you have Watchtower set to keep old images then over time they will pile up on your system and take up valuable space. Remember to delete old unused docker container images to keep your system running smoothly.