Introduction

Overview

Watchtower is an application that will monitor your running Docker containers and watch for changes to the images that those containers were originally started from. If Watchtower detects that an image has changed, it will automatically restart the container using the new image.

With Watchtower you can update the container by pushing a new image to the registry that’s repective to the container’s image. Watchtower will pull the new image, gracefully shut down the existing container, and restart it with the same options that were used when it was deployed initially.

How Image Updates Work

Watchtower monitors containers using their exact image reference, including any tags specified.

This means:

• A container running nginx:1.29 will only be updated when new images become available under the nginx:1.29 tag
• It will not update when nginx:latest, nginx:1.30, or other tags receive updates
• A container running myapp (without a tag) will update when myapp:latest changes

This tag-specific behavior provides fine-grained control over update scopes, allowing you to pin containers to specific versions while still receiving updates within that version series.

Examples of Different Tagging Schemes

While semantic versioning is ideal for predictable updates, many popular Docker images use different approaches.

The following examples show how Watchtower handles various tag types:

CONTAINER ID   IMAGE          STATUS          PORTS                    NAMES
abc123def456   nginx:latest   Up 10 minutes   0.0.0.0:80->80/tcp       webserver

CONTAINER ID   IMAGE          STATUS          PORTS                    NAMES
def456ghi789   nginx:1.29     Up 10 minutes   0.0.0.0:80->80/tcp       webserver

CONTAINER ID   IMAGE               STATUS          PORTS                    NAMES
ghi789jkl012   pihole/pihole:2023.11   Up 10 minutes   0.0.0.0:8080->80/tcp   pihole