# Watchtower — Automated Docker Container Image Updates

> Runs as a container itself, polls registries for new image tags, and gracefully redeploys running containers when updates appear.

## Install

Save in your project root:

# Watchtower — Automated Docker Container Image Updates

## Quick Use
```bash
# Update every container on the host every 5 minutes
docker run -d --name watchtower 
  -v /var/run/docker.sock:/var/run/docker.sock 
  containrrr/watchtower --interval 300 --cleanup

# Only update containers with a label
docker run --label=com.centurylinklabs.watchtower.enable=true 
  -d nginx:latest
```

## 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/

---
Source: https://tokrepo.com/en/workflows/1487461c-3919-11f1-9bc6-00163e2b0d79
Author: AI Open Source