Automate Docker Container Updates with Watchtower

Overview

Updating Docker containers manually is similar to installing a mobile app: you must stop the container, remove it, pull the new image, and run it again. For many containers this process is tedious, especially when frequent updates are required.

Watchtower

Watchtower is a Docker image that continuously monitors running containers for newer image versions. When an update is detected, it gracefully stops the container with a SIGTERM, pulls the new image, and restarts the container using the original parameters, all without user interaction.

It works by polling the Docker daemon at regular intervals, pulling newer images when available, and optionally cleaning up old images.

Official site: https://containrrr.dev/watchtower

Basic Usage

Update All Containers on the Host

Run the following command to update every container on the host, including Watchtower itself.

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower

Watch a Specific Container

Add the container name to the command to monitor only that container.

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  miniboard

Set Update Frequency

By default Watchtower checks for updates every 24 hours. Use --interval (seconds) to change the polling period.

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --interval 6

You can also use --schedule with a cron expression to define a specific schedule, e.g., "0 30 20 * * 5" runs at 20:30 on Fridays.

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --schedule "0 30 20 * * 5"

Automatic Cleanup of Old Images

Include --cleanup so that each update removes the previous image, freeing disk space.

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --cleanup

Configure Update Intervals

Watchtower’s default poll interval is 5 minutes. You can adjust it with the following options: --interval or -i: set the interval in seconds (default 300). --schedule or -s: provide a cron expression, e.g., "0 0 1 * * *" to run daily at 01:00.

Example: update every 2 hours.

docker run -d \
  --name watchtower \
  --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --cleanup \
  -i 7200

Example: update daily at 03:00.

docker run -d \
  --name watchtower \
  --restart always \
  -e TZ=Asia/Shanghai \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --cleanup \
  -s "0 0 3 * * *"

Manual Update

Run Watchtower once with --rm and --run-once to update containers immediately. You can combine these with --cleanup and specify target containers or exclusions.

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --cleanup \
  --run-once

Update all containers:

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --cleanup \
  --run-once

Update specific containers (e.g., nginx and redis):

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --cleanup \
  --run-once \
  nginx redis