# containrrr/watchtower architecture

> Architecture diagram of the GitHub repository containrrr/watchtower, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/containrrr/watchtower
- Repository: https://github.com/containrrr/watchtower

## Overview

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: [`internal/actions/update.go`](https://github.com/containrrr/watchtower/blob/main/internal/actions/update.go) (Update orchestration), [`cmd/root.go`](https://github.com/containrrr/watchtower/blob/main/cmd/root.go) (Watchtower CLI), [`pkg/container/client.go`](https://github.com/containrrr/watchtower/blob/main/pkg/container/client.go) (Docker client), [`pkg/api/api.go`](https://github.com/containrrr/watchtower/blob/main/pkg/api/api.go) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Scan control"]
  node_cli["Watchtower CLI<br/>[root.go]"]
  node_scheduler["Scan scheduler<br/>[root.go]"]
  node_http_api["HTTP API<br/>[api.go]"]
  node_update_api["Update endpoint<br/>[update.go]"]
  node_filters["Container filters<br/>[filters.go]"]
end

subgraph group_updates["Update workflow"]
  node_actions["Update orchestration<br/>[update.go]"]
  node_check["Image check<br/>[check.go]"]
  node_docker_client["Docker client<br/>[client.go]"]
  node_container_model["Container model<br/>[container.go]"]
  node_lifecycle["Lifecycle hooks<br/>[lifecycle.go]"]
end

subgraph group_registry["Image registry"]
  node_registry_client["Registry access<br/>[registry.go]"]
  node_registry_auth["Registry authentication<br/>[auth.go]"]
  node_digest["Image digest check<br/>[digest.go]"]
end

subgraph group_outputs["Reports and outputs"]
  node_report["Scan report<br/>[report.go]"]
  node_metrics["Prometheus metrics<br/>[metrics.go]"]
  node_metrics_api["Metrics endpoint<br/>[metrics.go]"]
end

subgraph group_notify["Notifications"]
  node_notifier["Notification dispatcher<br/>[notifier.go]"]
  node_notification_channels["Notification channels"]
end

node_operator(("Operator"))
node_docker_engine["Docker Engine"]
node_image_registry["Image registry"]
node_notification_services["Notification services"]

node_operator -->|"starts"| node_cli
node_cli -->|"builds filters"| node_filters
node_cli -->|"configures scans"| node_scheduler
node_cli -->|"starts server"| node_http_api
node_http_api -->|"registers endpoint"| node_update_api
node_update_api -.->|"triggers scan"| node_actions
node_scheduler -->|"runs scans"| node_actions
node_actions -->|"uses filter"| node_filters
node_actions -->|"checks images"| node_check
node_actions -->|"manages containers"| node_docker_client
node_actions -->|"runs hooks"| node_lifecycle
node_docker_client -->|"controls containers"| node_docker_engine
node_docker_client -->|"converts metadata"| node_container_model
node_docker_client -->|"loads pull credentials"| node_registry_client
node_docker_client -->|"checks image digest"| node_digest
node_registry_client -->|"requests credentials"| node_registry_auth
node_registry_auth -->|"requests auth token"| node_image_registry
node_digest -.->|"compares image digest"| node_image_registry
node_actions -->|"builds report"| node_report
node_cli -->|"registers scan metrics"| node_metrics
node_metrics_api -->|"exposes metrics"| node_metrics
node_cli -->|"configures notifications"| node_notifier
node_notifier -->|"dispatches messages"| node_notification_channels
node_notification_channels -.->|"sends notifications"| node_notification_services

click node_cli "https://github.com/containrrr/watchtower/blob/main/cmd/root.go"
click node_scheduler "https://github.com/containrrr/watchtower/blob/main/cmd/root.go"
click node_http_api "https://github.com/containrrr/watchtower/blob/main/pkg/api/api.go"
click node_update_api "https://github.com/containrrr/watchtower/blob/main/pkg/api/update/update.go"
click node_filters "https://github.com/containrrr/watchtower/blob/main/pkg/filters/filters.go"
click node_actions "https://github.com/containrrr/watchtower/blob/main/internal/actions/update.go"
click node_check "https://github.com/containrrr/watchtower/blob/main/internal/actions/check.go"
click node_docker_client "https://github.com/containrrr/watchtower/blob/main/pkg/container/client.go"
click node_container_model "https://github.com/containrrr/watchtower/blob/main/pkg/container/container.go"
click node_lifecycle "https://github.com/containrrr/watchtower/blob/main/pkg/lifecycle/lifecycle.go"
click node_registry_client "https://github.com/containrrr/watchtower/blob/main/pkg/registry/registry.go"
click node_registry_auth "https://github.com/containrrr/watchtower/blob/main/pkg/registry/auth/auth.go"
click node_digest "https://github.com/containrrr/watchtower/blob/main/pkg/registry/digest/digest.go"
click node_report "https://github.com/containrrr/watchtower/blob/main/pkg/session/report.go"
click node_metrics "https://github.com/containrrr/watchtower/blob/main/pkg/metrics/metrics.go"
click node_metrics_api "https://github.com/containrrr/watchtower/blob/main/pkg/api/metrics/metrics.go"
click node_notifier "https://github.com/containrrr/watchtower/blob/main/pkg/notifications/notifier.go"
click node_notification_channels "https://github.com/containrrr/watchtower/tree/main/pkg/notifications"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_scheduler,node_http_api,node_update_api,node_filters toneBlue
class node_actions,node_check,node_docker_client,node_container_model,node_lifecycle toneAmber
class node_registry_client,node_registry_auth,node_digest toneMint
class node_report,node_metrics,node_metrics_api toneRose
class node_notifier,node_notification_channels,node_operator,node_docker_engine,node_image_registry,node_notification_services toneIndigo
```

## Components

### Scan control

- [Watchtower CLI](https://github.com/containrrr/watchtower/blob/main/cmd/root.go): `cmd/root.go`
- [Scan scheduler](https://github.com/containrrr/watchtower/blob/main/cmd/root.go): `cmd/root.go`
- [HTTP API](https://github.com/containrrr/watchtower/blob/main/pkg/api/api.go): `pkg/api/api.go`
- [Update endpoint](https://github.com/containrrr/watchtower/blob/main/pkg/api/update/update.go): `pkg/api/update/update.go`
- [Container filters](https://github.com/containrrr/watchtower/blob/main/pkg/filters/filters.go): `pkg/filters/filters.go`

### Update workflow

- [Update orchestration](https://github.com/containrrr/watchtower/blob/main/internal/actions/update.go): `internal/actions/update.go`
- [Image check](https://github.com/containrrr/watchtower/blob/main/internal/actions/check.go): `internal/actions/check.go`
- [Docker client](https://github.com/containrrr/watchtower/blob/main/pkg/container/client.go): `pkg/container/client.go`
- [Container model](https://github.com/containrrr/watchtower/blob/main/pkg/container/container.go): `pkg/container/container.go`
- [Lifecycle hooks](https://github.com/containrrr/watchtower/blob/main/pkg/lifecycle/lifecycle.go): `pkg/lifecycle/lifecycle.go`

### Image registry

- [Registry access](https://github.com/containrrr/watchtower/blob/main/pkg/registry/registry.go): `pkg/registry/registry.go`
- [Registry authentication](https://github.com/containrrr/watchtower/blob/main/pkg/registry/auth/auth.go): `pkg/registry/auth/auth.go`
- [Image digest check](https://github.com/containrrr/watchtower/blob/main/pkg/registry/digest/digest.go): `pkg/registry/digest/digest.go`

### Reports and outputs

- [Scan report](https://github.com/containrrr/watchtower/blob/main/pkg/session/report.go): `pkg/session/report.go`
- [Prometheus metrics](https://github.com/containrrr/watchtower/blob/main/pkg/metrics/metrics.go): `pkg/metrics/metrics.go`
- [Metrics endpoint](https://github.com/containrrr/watchtower/blob/main/pkg/api/metrics/metrics.go): `pkg/api/metrics/metrics.go`

### Notifications

- [Notification dispatcher](https://github.com/containrrr/watchtower/blob/main/pkg/notifications/notifier.go): `pkg/notifications/notifier.go`
- [Notification channels](https://github.com/containrrr/watchtower/tree/main/pkg/notifications): `pkg/notifications`

### Other components

- **Operator**
- **Docker Engine**
- **Image registry**
- **Notification services**

## Connections

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