Watchtower — Automated Docker Container Image Updates

Introduction

Watchtower removes the toil of docker pull && docker-compose up -d from a homelab or edge fleet. It watches the registry behind each running container and, when a newer digest appears for the same tag, it stops the old container, pulls the new image, and starts it back up with the original configuration.

What Watchtower Does

• Polls any Docker registry (Docker Hub, GHCR, ECR, ACR, private) on a schedule.
• Compares image digests, not tags — "latest" pointing at a new SHA triggers an update.
• Preserves ports, networks, volumes, env vars, labels, and restart policy.
• Drains and recreates containers in dependency order via depends_on.
• Sends notifications to Slack, Email, Discord, Gotify, Pushover, or webhooks.

Architecture Overview

One Go binary with the Docker socket mounted. It introspects running containers, pulls images in parallel using the Docker Engine API, and orchestrates stop/remove/create/start cycles. Remote hosts are supported via the Docker TCP socket with TLS client certs; a single Watchtower can manage a whole fleet.

Self-Hosting & Configuration

• Monitor only labeled containers: --label-enable + com.centurylinklabs.watchtower.enable=true.
• Protect yourself from bad releases: --label-take-precedence and depends-on flags.
• WATCHTOWER_NOTIFICATIONS=slack plus token env vars enable chat alerts.
• --rolling-restart keeps one replica up at a time in small swarms.
• Pin sensitive images (traefik:3.1) and let Watchtower upgrade only minor changes.

Key Features

• Stateless — blow it away and reinstall, state lives in your containers.
• Private registry auth via /root/.docker/config.json volume mount.
• HTTP API lets CI systems trigger a forced update.
• Metrics endpoint exposes update counts and failure stats.
• Works on arm64, armv7, and amd64 — perfect for Raspberry Pi racks.

Comparison with Similar Tools

• Renovate / Dependabot — edit manifests, not running containers; more review-friendly.
• Portainer Edge Agent — GUI-driven, lacks Watchtower's zero-touch upgrades.
• Diun — notifications only, you still update manually.
• Shepherd — Swarm-focused service updater.
• Kured + Flux — Kubernetes equivalent for GitOps rollouts.

FAQ

Q: Is it safe on production? A: Use tag pinning and labels, review changelogs, and run a staging fleet first — Watchtower will faithfully apply whatever the registry serves.

Q: What about Compose stacks? A: Watchtower honors compose labels and recreates the container with the same settings.

Q: Archived — is it dead? A: The original repo is archived, but the image still receives security builds and community forks (nicolargo/watchtower, beatkind/watchtower) continue active development.

Q: Kubernetes? A: Use Keel or Flux — Watchtower is Docker-only by design.

Sources

• https://github.com/containrrr/watchtower
• https://containrrr.dev/watchtower/