containrrr/watchtower

How containrrr/watchtower works

Watchtower automates updates to running Docker containers: it selects containers, checks their images against registries, then replaces stale containers while preserving deployment settings. It also supports scheduled or API-triggered scans, lifecycle hooks, reports, Prometheus metrics, and notifications. The graph emphasizes these documented capabilities and the sampled calls; some subsystem links are based on SOURCE INDEX references or README statements because their implementation excerpts were not provided.

Main entry points: update.go Update orchestration · root.go Watchtower CLI · client.go Docker client · api.go HTTP API

Components 22

Scan control

Watchtower CLI cmd/root.go
Scan scheduler cmd/root.go
HTTP API pkg/api/api.go
Update endpoint pkg/api/update/update.go
Container filters pkg/filters/filters.go

Update workflow

Update orchestration internal/actions/update.go
Image check internal/actions/check.go
Docker client pkg/container/client.go
Container model pkg/container/container.go
Lifecycle hooks pkg/lifecycle/lifecycle.go

Image registry

Registry access pkg/registry/registry.go
Registry authentication pkg/registry/auth/auth.go
Image digest check pkg/registry/digest/digest.go

Reports and outputs

Scan report pkg/session/report.go
Prometheus metrics pkg/metrics/metrics.go
Metrics endpoint pkg/api/metrics/metrics.go

Notifications

Notification dispatcher pkg/notifications/notifier.go
Notification channels pkg/notifications

Other components

Operator
Docker Engine
Image registry
Notification services

Connections 24

Operator → Watchtower CLI: starts README.md
Watchtower CLI → Container filters: builds filters cmd/root.go
Watchtower CLI → Scan scheduler: configures scans cmd/root.go
Watchtower CLI → HTTP API: starts server cmd/root.go
HTTP API → Update endpoint: registers endpoint
Update endpoint → Update orchestration: triggers scan
Scan scheduler → Update orchestration: runs scans cmd/root.go
Update orchestration → Container filters: uses filter internal/actions/update.go
Update orchestration → Image check: checks images internal/actions/check.go
Update orchestration → Docker client: manages containers internal/actions/update.go
Update orchestration → Lifecycle hooks: runs hooks internal/actions/update.go
Docker client → Docker Engine: controls containers README.md
Docker client → Container model: converts metadata pkg/container/client.go
Docker client → Registry access: loads pull credentials pkg/container/client.go
Docker client → Image digest check: checks image digest pkg/container/client.go
Registry access → Registry authentication: requests credentials pkg/registry/auth/auth.go
Registry authentication → Image registry: requests auth token pkg/registry/auth/auth.go
Image digest check → Image registry: compares image digest
Update orchestration → Scan report: builds report internal/actions/update.go
Watchtower CLI → Prometheus metrics: registers scan metrics cmd/root.go
Metrics endpoint → Prometheus metrics: exposes metrics pkg/api/metrics/metrics.go
Watchtower CLI → Notification dispatcher: configures notifications cmd/root.go
Notification dispatcher → Notification channels: dispatches messages pkg/notifications/notifier.go
Notification channels → Notification services: sends notifications

More Go diagrams: go-delve/delve · gorilla/websocket · uber-go/zap · inconshreveable/ngrok · urfave/cli

Drawn by GitDiagram on September 30, 2026 from the repository's file tree, README and source files. Read as Markdown ·