How to Automatically Update Running Docker Containers with Watchtower

Attribution: This article is based on content originally published at ostechnix.com.

What Is Watchtower?

Watchtower is a free, open-source application that monitors your running Docker containers and automatically updates them when it detects changes in their base images. The update process works as follows:

• Watchtower polls the image registry to detect changes to base images used by running containers.
• When an update is found, it gracefully stops the affected container by sending it a SIGTERM signal.
• It pulls the updated image from the registry.
• It restarts the container using the same runtime options — volumes, environment variables, port bindings, etc. — that were used when the container was originally launched.

The entire lifecycle is handled automatically in the background. No manual intervention is needed, making Watchtower useful in environments where keeping containers up to date is a routine operational requirement.

The steps in this guide were originally tested on CentOS 7 minimal edition, but the procedure applies to any Linux distribution that supports Docker.

Prerequisites

Watchtower is itself distributed as a Docker image, so the only prerequisite is a working Docker installation. Install Docker for your distribution before proceeding:

• For RPM-based systems (CentOS, RHEL, Fedora): follow the official Docker documentation for your distribution.
• For DEB-based systems (Ubuntu, Debian): follow the official Docker documentation for your distribution.

Installing Watchtower

Because Watchtower is packaged as a Docker image, deploying it requires only a single docker run command. Run the following as root or as a user with Docker socket access:

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  v2tec/watchtowerCode language: JavaScript (javascript)

Breaking down the flags:

• -d — Run the container in detached (background) mode.
• --name watchtower — Assign the container a recognisable name.
• -v /var/run/docker.sock:/var/run/docker.sock — Mount the Docker daemon socket so Watchtower can inspect and manage other containers on the host.
• v2tec/watchtower — The official Watchtower image (pulls latest by default).

Expected output when the image is pulled for the first time:

Unable to find image 'v2tec/watchtower:latest' locally
latest: Pulling from v2tec/watchtower
a3ed95caeb02: Pull complete
802d894958a2: Pull complete
9916c27d2815: Pull complete
Digest: sha256:d89ea18b6332cc83639771fda274ebfd76f7042856d8f4997e99c7925ad02ae9
Status: Downloaded newer image for v2tec/watchtower:latest
e85c923f2e4dd22a62c12b038ea9694ba9245dcd835f210e1Code language: JavaScript (javascript)

Verifying the Watchtower Container Is Running

Confirm that Watchtower is running alongside your other containers:

docker ps

Sample output:

CONTAINER ID   IMAGE              COMMAND          CREATED         STATUS         PORTS   NAMES
e85c923f2e4d   v2tec/watchtower   "/watchtower"    3 minutes ago   Up 3 minutes           watchtower
58543e6ed18a   centos:latest      "/bin/bash"      5 minutes ago   Up 5 minutes           myappCode language: JavaScript (javascript)

Watchtower is now running and will begin polling all other running containers on the host for image updates at regular intervals.

Monitoring All Containers vs. Specific Containers

Monitor All Containers (Default Behaviour)

By default, Watchtower monitors every container managed by the Docker daemon it is connected to. No additional configuration is needed — the basic docker run command above is sufficient.

Monitor Only Specific Containers

If you want Watchtower to watch only certain containers, append the container names as arguments at the end of the docker run command:

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  v2tec/watchtower myappCode language: JavaScript (javascript)

In this example, Watchtower will watch only the container named myapp. All other running containers are ignored. You can supply multiple container names as space-separated arguments:

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  v2tec/watchtower myapp nginx redisCode language: JavaScript (javascript)

How the Update Cycle Works

Once Watchtower is running, it periodically checks the image registry for updates to the base images of each monitored container. The default polling interval is every 5 minutes. When an updated image is found:

1. Watchtower sends a SIGTERM to the running container, allowing it to shut down gracefully.
2. The new image is pulled from the registry.
3. A replacement container is started using the exact same configuration — including environment variables, port mappings, volume mounts, and network settings — as the original.

This behaviour means that Watchtower is best suited for stateless or semi-stateless workloads where restarting the container with the same options produces the desired result. For stateful services, consider whether an automated restart without a migration or data-backup step is appropriate for your workload.

Security Consideration: Docker Socket Access

Mounting the Docker socket (/var/run/docker.sock) into any container grants that container root-equivalent access to the Docker daemon and, by extension, to the host. This is an inherent requirement of how Watchtower operates. Ensure that:

• The host’s Docker socket permissions are appropriately restricted.
• You trust the Watchtower image source and pin to a specific image digest in production environments rather than using the latest tag.
• You review Watchtower’s own release notes before allowing it to update itself.

Summary

Watchtower provides a straightforward mechanism for keeping Docker containers up to date without manual re-deployment steps. By running it as a sidecar container with access to the Docker socket, it can monitor any number of containers and automatically apply base-image updates on a configurable schedule. For simple, stateless container workloads, this can significantly reduce operational overhead.

For more advanced use cases — such as sending update notifications, configuring custom polling intervals, or integrating with private registries — consult the official Watchtower documentation.