README
¶
Watchtower
Automate Docker container image updates
Quick Start
With watchtower you can update the running version of your containerized app simply by pushing a new image to the Docker Hub or your own image registry.
Watchtower will pull down your new image, gracefully shut down your existing container and restart it with the same options that were used when it was deployed initially. Run the watchtower container with the following command:
$ docker run --detach \
--name watchtower \
--volume /var/run/docker.sock:/var/run/docker.sock \
ghcr.io/sidneyojr/watchtower
Watchtower is intended to be used in homelabs, media centers, local dev environments, and similar. We do not recommend using Watchtower in a commercial or production environment. If that is you, you should be looking into using Kubernetes enabled with CI/CD, such as onedr0p's Talos Linux with FluxCD setup here.
⚠️ Note: It is recommended to use the latest version of Docker. You can check your host's Docker version using the CLI command docker version.
This version of Watchtower has been tested to support v1.43 and higher; however, don't be surprised if you experience unexpected behavior when attempting to use newer features on older versions of Docker.
This version autonegotiates the API version by default. If the DOCKER_API_VERSION variable is explicitly set, Watchtower validates the version and falls back to autonegotiation on failure.
Supported Architectures
Watchtower supports the following architectures for its Docker images:
- amd64
- i386
- armhf
- arm64v8
- riscv64
Documentation
The full documentation is available at https://sidneyojr.github.io/watchtower/.
Contributors
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
Documentation
¶
Overview ¶
@title Watchtower HTTP API @version 1.0 @description Watchtower HTTP API for container update management, metrics, and health probes. @contact.name sidneyojr @contact.url https://github.com/sidneyojr/watchtower @license.name MIT @license.url https://opensource.org/licenses/MIT @host localhost:8080 @BasePath / @schemes http https @accept json @produce json @securityDefinitions.apikey BearerAuth @in header @name Authorization @description Paste the HTTP API token only (WATCHTOWER_HTTP_API_TOKEN). Swagger UI sends it as the Authorization header value. curl clients should use "Authorization: Bearer <token>". @securityDefinitions.apikey EventsToken @in header @name Authorization @description Paste the events API token only (WATCHTOWER_HTTP_API_EVENTS_TOKEN). Swagger UI sends it as the Authorization header value. @tag.name health @tag.description Standardized liveness, readiness, and startup probes @tag.name update @tag.description Trigger and manage container image updates @tag.name metrics @tag.description Prometheus metrics and scan status @tag.name containers @tag.description Watched container image identity and update availability @tag.name check @tag.description Check for available container updates without applying them @tag.name history @tag.description Historical scan results from the in-memory ring buffer @tag.name images @tag.description Tracked images with digests and container counts @tag.name config @tag.description Active Watchtower configuration settings @tag.name events @tag.description Real-time operational events via Server-Sent Events
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cmd contains the command-line interface (CLI) definitions and execution logic for Watchtower.
|
Package cmd contains the command-line interface (CLI) definitions and execution logic for Watchtower. |
|
examples
|
|
|
lifecycle-hooks/synology-stop
command
Package synology-stop is a Watchtower "stop" lifecycle hook that performs graceful Docker container shutdown on Synology DSM using the official Web API.
|
Package synology-stop is a Watchtower "stop" lifecycle hook that performs graceful Docker container shutdown on Synology DSM using the official Web API. |
|
internal
|
|
|
actions
Package actions provides core logic for Watchtower's container update operations.
|
Package actions provides core logic for Watchtower's container update operations. |
|
actions/mocks
Package mocks provides mock implementations for testing Watchtower components.
|
Package mocks provides mock implementations for testing Watchtower components. |
|
api
Package api provides Watchtower's HTTP API server, built on Fiber v3.
|
Package api provides Watchtower's HTTP API server, built on Fiber v3. |
|
api/config
Package config defines the shared configuration types, validation functions, and sentinel errors used across the API packages.
|
Package config defines the shared configuration types, validation functions, and sentinel errors used across the API packages. |
|
api/handlers/check
Package check provides the /v1/check endpoint for read-only update availability checks.
|
Package check provides the /v1/check endpoint for read-only update availability checks. |
|
api/handlers/config
Package config provides the HTTP handler for the /v1/config endpoint.
|
Package config provides the HTTP handler for the /v1/config endpoint. |
|
api/handlers/containers
Package containers provides the /v1/containers HTTP API endpoint, exposing the current image identity (name, local ID, and registry manifest digest) of each container Watchtower watches.
|
Package containers provides the /v1/containers HTTP API endpoint, exposing the current image identity (name, local ID, and registry manifest digest) of each container Watchtower watches. |
|
api/handlers/containers/details
Package details provides the /v1/containers/details HTTP API endpoint, exposing detailed information about a single watched container including its image identity, digest, and update availability status.
|
Package details provides the /v1/containers/details HTTP API endpoint, exposing detailed information about a single watched container including its image identity, digest, and update availability status. |
|
api/handlers/events
Package events provides the /v1/events HTTP API endpoint for real-time Server-Sent Events (SSE).
|
Package events provides the /v1/events HTTP API endpoint for real-time Server-Sent Events (SSE). |
|
api/handlers/health
Package health provides HTTP health check handlers for Watchtower.
|
Package health provides HTTP health check handlers for Watchtower. |
|
api/handlers/history
Package history provides the /v1/history HTTP API endpoint, exposing historical scan results from the in-memory ring buffer (up to 500 entries).
|
Package history provides the /v1/history HTTP API endpoint, exposing historical scan results from the in-memory ring buffer (up to 500 entries). |
|
api/handlers/images
Package images provides the /v1/images HTTP API endpoint, exposing the current image identity (name, local ID, registry manifest digest) and container count for each image Watchtower tracks.
|
Package images provides the /v1/images HTTP API endpoint, exposing the current image identity (name, local ID, registry manifest digest) and container count for each image Watchtower tracks. |
|
api/handlers/metrics
Package metrics provides the /v1/metrics HTTP API endpoint for serving Prometheus metrics.
|
Package metrics provides the /v1/metrics HTTP API endpoint for serving Prometheus metrics. |
|
api/handlers/update
Package update provides an HTTP API handler for triggering Watchtower container updates.
|
Package update provides an HTTP API handler for triggering Watchtower container updates. |
|
api/routes
Package routes registers all enabled API endpoints on a Fiber application.
|
Package routes registers all enabled API endpoints on a Fiber application. |
|
api/swagger
Package swagger Code generated by swaggo/swag.
|
Package swagger Code generated by swaggo/swag. |
|
config
Package config resolves process configuration into a single immutable Config.
|
Package config resolves process configuration into a single immutable Config. |
|
config/api
Package api holds HTTP API transport and endpoint settings.
|
Package api holds HTTP API transport and endpoint settings. |
|
config/client
Package client holds Docker client construction options derived from flags.
|
Package client holds Docker client construction options derived from flags. |
|
config/compatibility
Package compatibility holds runtime compatibility settings (for example Podman).
|
Package compatibility holds runtime compatibility settings (for example Podman). |
|
config/docker
Package docker holds Docker API connection settings.
|
Package docker holds Docker API connection settings. |
|
config/filter
Package filter holds container selection inputs and the resolved filter.
|
Package filter holds container selection inputs and the resolved filter. |
|
config/lifecycle
Package lifecycle holds pre/post update lifecycle hook settings.
|
Package lifecycle holds pre/post update lifecycle hook settings. |
|
config/logging
Package logging holds console logging settings.
|
Package logging holds console logging settings. |
|
config/mode
Package mode holds process entry-shape settings.
|
Package mode holds process entry-shape settings. |
|
config/notify
Package notify holds notification settings for the config domain.
|
Package notify holds notification settings for the config domain. |
|
config/registry
Package registry holds registry TLS settings.
|
Package registry holds registry TLS settings. |
|
config/schedule
Package schedule holds poll interval and cron schedule settings.
|
Package schedule holds poll interval and cron schedule settings. |
|
config/update
Package update holds container update policy settings.
|
Package update holds container update policy settings. |
|
flags
Package flags manages command-line flags and environment variables for Watchtower configuration.
|
Package flags manages command-line flags and environment variables for Watchtower configuration. |
|
flags/api
Package api registers HTTP API transport and endpoint flags.
|
Package api registers HTTP API transport and endpoint flags. |
|
flags/client
Package client registers Docker client construction flags.
|
Package client registers Docker client construction flags. |
|
flags/compat
Package compat registers runtime compatibility flags.
|
Package compat registers runtime compatibility flags. |
|
flags/docker
Package docker registers Docker API client flags.
|
Package docker registers Docker API client flags. |
|
flags/filter
Package filter registers container selection flags.
|
Package filter registers container selection flags. |
|
flags/lifecycle
Package lifecycle registers pre/post update lifecycle hook flags.
|
Package lifecycle registers pre/post update lifecycle hook flags. |
|
flags/logging
Package logging registers console logging flags.
|
Package logging registers console logging flags. |
|
flags/mode
Package mode registers process entry-shape flags.
|
Package mode registers process entry-shape flags. |
|
flags/notify
Package notify registers notification-related CLI and environment flags.
|
Package notify registers notification-related CLI and environment flags. |
|
flags/registry
Package registry registers registry TLS flags.
|
Package registry registers registry TLS flags. |
|
flags/schedule
Package schedule registers poll interval and cron schedule flags.
|
Package schedule registers poll interval and cron schedule flags. |
|
flags/spec
Package spec defines shared flag metadata used by domain registration and Viper bind.
|
Package spec defines shared flag metadata used by domain registration and Viper bind. |
|
flags/update
Package update registers container update policy flags.
|
Package update registers container update policy flags. |
|
flags/utils
Package utils provides shared helpers for flag registration and value parsing.
|
Package utils provides shared helpers for flag registration and value parsing. |
|
logging
Package logging provides zerolog construction and configuration helpers for Watchtower.
|
Package logging provides zerolog construction and configuration helpers for Watchtower. |
|
meta
Package meta provides centralized application metadata for Watchtower.
|
Package meta provides centralized application metadata for Watchtower. |
|
metrics
Package metrics provides tracking and exposure of Watchtower scan metrics.
|
Package metrics provides tracking and exposure of Watchtower scan metrics. |
|
scheduling
Package scheduling provides functionality for scheduling and executing container updates in Watchtower.
|
Package scheduling provides functionality for scheduling and executing container updates in Watchtower. |
|
util
Package util provides utility functions for Watchtower operations.
|
Package util provides utility functions for Watchtower operations. |
|
pkg
|
|
|
compose
Package compose provides functionality for handling Docker Compose-specific logic, including parsing depends_on labels and extracting service names for dependency management.
|
Package compose provides functionality for handling Docker Compose-specific logic, including parsing depends_on labels and extracting service names for dependency management. |
|
container
Package container provides functionality for managing Docker containers in Watchtower.
|
Package container provides functionality for managing Docker containers in Watchtower. |
|
container/mocks
Package mocks provides hand-written HTTP API fixtures and Mockery-generated doubles for container package tests.
|
Package mocks provides hand-written HTTP API fixtures and Mockery-generated doubles for container package tests. |
|
filters
Package filters provides filtering logic for Watchtower containers.
|
Package filters provides filtering logic for Watchtower containers. |
|
lifecycle
Package lifecycle manages execution of lifecycle hooks for Watchtower containers.
|
Package lifecycle manages execution of lifecycle hooks for Watchtower containers. |
|
notifications
Package notifications provides the notification client for sending Watchtower update messages.
|
Package notifications provides the notification client for sending Watchtower update messages. |
|
registry
Package registry provides functionality for interacting with container registries in Watchtower.
|
Package registry provides functionality for interacting with container registries in Watchtower. |
|
registry/auth
Package auth implements the Docker Registry HTTP API V2 authentication protocol.
|
Package auth implements the Docker Registry HTTP API V2 authentication protocol. |
|
registry/digest
Package digest provides functionality for retrieving and comparing Docker image digests in Watchtower.
|
Package digest provides functionality for retrieving and comparing Docker image digests in Watchtower. |
|
registry/manifest
Package manifest provides functionality for constructing URLs to access container image manifests in Watchtower.
|
Package manifest provides functionality for constructing URLs to access container image manifests in Watchtower. |
|
session
Package session manages container states and reporting during a Watchtower update session.
|
Package session manages container states and reporting during a Watchtower update session. |
|
sorter
Package sorter provides sorting functionality for Watchtower containers.
|
Package sorter provides sorting functionality for Watchtower containers. |
|
sorter/mocks
Package mocks provides mock implementations for container interfaces used in testing.
|
Package mocks provides mock implementations for container interfaces used in testing. |
|
types
Package types defines core interfaces and structs for Watchtower.
|
Package types defines core interfaces and structs for Watchtower. |