Controlled Docker Image Updates with Watchtower: Preview, Cleanup, and Stopped Containers

Watchtower monitors Docker containers for changes to their source images and can restart them with a newer image. The i12bretro tutorial separates preview, update, and cleanup; Review the changes before enabling an automated update command.¹

1. Pull the Watchtower image

Step 1/10: Log into the Docker host.

Step 2/10: Pull the image:

docker pull containrrr/watchtower

2. Check for updates without applying them

Step 3/10: Log into the Docker host.

Step 4/10: Run one monitor-only pass, including restarting and stopped containers:

docker run --rm -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower --run-once --monitor-only --include-restarting --include-stopped

This requires access to the Docker socket; the output is the Watchtower check activity. I use this pass first to see what would be affected.

3. Update running containers

Step 5/10: Log into the Docker host.

Step 6/10: Run one update pass:

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

4. Update running containers and remove old images

Step 7/10: Log into the Docker host.

Step 8/10: Run cleanup:

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

--cleanup removes old images, so I check tags, persistent volumes, and rollback options before using it.

5. Update all containers, including restarting/stopped, then clean up

Step 9/10: Log into the Docker host.

Step 10/10: Run the broadest command:

docker run --rm -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower --run-once --cleanup --include-restarting --include-stopped

This has the widest scope in the tutorial. I would not turn it into a cron job without backups and an exclusion policy; access to the Docker socket is effectively high-level host administration.

6. Notifications and checks

The source links separate notification instructions using environment variables. Read the corresponding Watchtower documentation before enabling them, and never put a webhook or token into public compose files or Markdown.¹

After each run:

docker ps
docker image ls
docker logs <container-name>

Check the application, persistent volumes, and migration logs before deleting old images. The tutorial provides one-shot commands, not a schedule, retention policy, or automatic rollback; those require a separate HomeLab design.

Conclusion

The 10 steps define four behaviors: pull the image, monitor-only, update, update plus cleanup, and a final pass that includes restarting/stopped containers. I start with monitor-only, clean up only after verifying the application, and keep the Docker socket limited to a trusted host.

Sources