Introduction¶
Deprecation Notice¶
Watchtower v2 Legacy Notification Deprecation
Watchtower has a number of legacy notification configuration options that will be removed with the release of Watchtower v2:
Migration to the NOTIFICATION URL with the appropriate Shoutrrr URL scheme is strongly recommended.
Use Watchtower's CLI migration tool to help convert legacy email configurations to Shoutrrr URLs or use the Shoutrrr Playground to help convert configurations for other services to Shoutrrr URLs.
Overview¶
By default, Watchtower monitors all containers running on the Docker daemon it connects to (typically the local daemon, configurable via the --host flag).
To limit monitoring to specific containers, provide their names as arguments when starting Watchtower.
- In the above example, Watchtower monitors only the
nginxandrediscontainers, ignoring others.
To run a single update attempt and exit, use the run-once configuration option.
- This command triggers an update attempt for "nginx" and "redis" containers, displays debug output, and removes the Watchtower container upon completion.
By default, Watchtower decides that an image is stale by comparing registry digests. Git monitoring is an optional alternate staleness signal: associate a container with a hosted repository, and Watchtower rebuilds from a Git URL context or a local Compose project directory when that ref changes. See Advanced Features → Git Monitoring.
Note
Regex patterns are supported. See Regex Pattern Matching for details.
Startup errors
When a configuration option or flag is invalid, Watchtower exits at startup.
- In a container, Watchtower first sets its restart policy to
no, so the container does not restart in a loop. - Start the container again once the configuration is fixed.
- A
--hostflag after an invalid flag is not read. Watchtower then connects throughDOCKER_HOSTor the default socket. - If Watchtower cannot change its restart policy, it logs an error.
General Options¶
Help¶
Displays documentation for supported flags.
Health Check¶
Returns a success exit code for Docker HEALTHCHECK, verifying another process is running in the container.
Note
Intended solely for Docker HEALTHCHECK.
Do not use on the main command line.
Health Check with Podman¶
Podman ignores the HEALTHCHECK instruction in the Watchtower image. The image is published in the OCI format, and Podman only reads health checks from images in the Docker format (containers/podman#18904). To enable the health check under Podman, define it in your container configuration, as shown below.
Note
- Use the exec form shown above. Because the image does not include a shell, a shell-form health check, such as
--health-cmd "/watchtower --health-check"or aCMD-SHELLtest, always reports the container as unhealthy. - Docker Compose requires
CMDas the first entry of thetestlist. Without it, Compose fails with the errorhealthcheck.test must start either by "CMD", "CMD-SHELL" or "NONE". - For rootless Podman, mount the socket from
$XDG_RUNTIME_DIR/podman/podman.sockinstead of/run/podman/podman.sock.