Andreas/watchtower
1
0
Fork 0
mirror of https://github.com/containrrr/watchtower.git synced 2025-09-21 21:30:48 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: update documentation with new sections and improve clarity

Browse source
This commit is contained in:
Jan Rundshagen 2025-03-29 13:11:47 +01:00 • committed by Jan O. Rundshagen
parent ca0d37a4ac
commit d2a21afcfe
20 changed files with 128 additions and 73 deletions
Download patch file Download diff file Expand all files Collapse all files

2
.gitignore vendored
View file

@ -12,3 +12,5 @@ coverage.out
docs/assets/wasm_exec.js docs/assets/wasm_exec.js
docs/assets/*.wasm docs/assets/*.wasm
.vscode/settings.json .vscode/settings.json
.env

4
CONTRIBUTING.md
View file

@ -12,7 +12,7 @@ You can check your current version of the go language as follows:
```bash ```bash
~ $ go version ~ $ go version
go version go1.22.x darwin/amd64 go version go1.24.x darwin/amd64
``` ```
## Checking out the code ## Checking out the code
@ -44,5 +44,5 @@ To build a Watchtower image of your own, use the self-contained Dockerfiles. As
e.g.: e.g.:
```bash ```bash
sudo docker build . -f dockerfiles/Dockerfile.dev-self-contained -t containrrr/watchtower # to build an image from local files sudo docker build . -f dockerfiles/Dockerfile.dev-self-contained -t beatkind/watchtower # to build an image from local files
``` ```

2
SECURITY.md
View file

@ -1,3 +1,3 @@
# Security Policy # Security Policy
Nothing here yet. We'll figure it out. Message me if you need something under: <github.retying350@silomails.com>. Nothing here yet. We'll figure it out. Message me if you need something under: <jan@devcdn.net>.

53
docs/arguments.md
View file

@ -1,3 +1,5 @@
# Arguments
By default, watchtower will monitor all containers running within the Docker daemon to which it is pointed (in most cases this By default, watchtower will monitor all containers running within the Docker daemon to which it is pointed (in most cases this
will be the local Docker daemon, but you can override it with the `--host` option described in the next section). However, you will be the local Docker daemon, but you can override it with the `--host` option described in the next section). However, you
can restrict watchtower to monitoring a subset of the running containers by specifying the container names as arguments when can restrict watchtower to monitoring a subset of the running containers by specifying the container names as arguments when
@ -33,14 +35,16 @@ Some arguments can also reference a file, in which case the contents of the file
This can be used to avoid putting secrets in the configuration file or command line. This can be used to avoid putting secrets in the configuration file or command line.
The following arguments are currently supported (including their corresponding `WATCHTOWER_` environment variables): The following arguments are currently supported (including their corresponding `WATCHTOWER_` environment variables):
- `notification-url`
- `notification-email-server-password` - `notification-url`
- `notification-slack-hook-url` - `notification-email-server-password`
- `notification-msteams-hook` - `notification-slack-hook-url`
- `notification-gotify-token` - `notification-msteams-hook`
- `http-api-token` - `notification-gotify-token`
- `http-api-token`
### Example docker-compose usage ### Example docker-compose usage
```yaml ```yaml
secrets: secrets:
access_token: access_token:
@ -55,6 +59,7 @@ services:
``` ```
## Help ## Help
Shows documentation about the supported flags. Shows documentation about the supported flags.
```text ```text
@ -65,6 +70,7 @@ Environment Variable: N/A
``` ```
## Time Zone ## Time Zone
Sets the time zone to be used by WatchTower's logs and the optional Cron scheduling argument (--schedule). If this environment variable is not set, Watchtower will use the default time zone: UTC. Sets the time zone to be used by WatchTower's logs and the optional Cron scheduling argument (--schedule). If this environment variable is not set, Watchtower will use the default time zone: UTC.
To find out the right value, see [this list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), find your location and use the value in _TZ Database Name_, e.g _Europe/Rome_. The timezone can alternatively be set by volume mounting your hosts /etc/localtime file. `-v /etc/localtime:/etc/localtime:ro` To find out the right value, see [this list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), find your location and use the value in _TZ Database Name_, e.g _Europe/Rome_. The timezone can alternatively be set by volume mounting your hosts /etc/localtime file. `-v /etc/localtime:/etc/localtime:ro`
@ -76,6 +82,7 @@ Environment Variable: TZ
``` ```
## Cleanup ## Cleanup
Removes old images after updating. When this flag is specified, watchtower will remove the old image after restarting a container with a new image. Use this option to prevent the accumulation of orphaned images on your system as containers are updated. Removes old images after updating. When this flag is specified, watchtower will remove the old image after restarting a container with a new image. Use this option to prevent the accumulation of orphaned images on your system as containers are updated.
```text ```text
@ -86,6 +93,7 @@ Environment Variable: WATCHTOWER_CLEANUP
``` ```
## Remove anonymous volumes ## Remove anonymous volumes
Removes anonymous volumes after updating. When this flag is specified, watchtower will remove all anonymous volumes from the container before restarting with a new image. Named volumes will not be removed! Removes anonymous volumes after updating. When this flag is specified, watchtower will remove all anonymous volumes from the container before restarting with a new image. Named volumes will not be removed!
```text ```text
@ -96,6 +104,7 @@ Environment Variable: WATCHTOWER_REMOVE_VOLUMES
``` ```
## Debug ## Debug
Enable debug mode with verbose logging. Enable debug mode with verbose logging.
!!! note "Notes" !!! note "Notes"
@ -110,6 +119,7 @@ Environment Variable: WATCHTOWER_DEBUG
``` ```
## Trace ## Trace
Enable trace mode with very verbose logging. Caution: exposes credentials! Enable trace mode with very verbose logging. Caution: exposes credentials!
!!! note "Notes" !!! note "Notes"
@ -146,6 +156,7 @@ Environment Variable: WATCHTOWER_LOG_FORMAT
``` ```
## ANSI colors ## ANSI colors
Disable ANSI color escape codes in log output. Disable ANSI color escape codes in log output.
```text ```text
@ -156,6 +167,7 @@ Environment Variable: NO_COLOR
``` ```
## Docker host ## Docker host
Docker daemon socket to connect to. Can be pointed at a remote Docker host by specifying a TCP endpoint as "tcp://hostname:port". Docker daemon socket to connect to. Can be pointed at a remote Docker host by specifying a TCP endpoint as "tcp://hostname:port".
```text ```text
@ -166,6 +178,7 @@ Environment Variable: DOCKER_HOST
``` ```
## Docker API version ## Docker API version
The API version to use by the Docker client for connecting to the Docker daemon. The minimum supported version is 1.44. The API version to use by the Docker client for connecting to the Docker daemon. The minimum supported version is 1.44.
```text ```text
@ -176,6 +189,7 @@ Environment Variable: DOCKER_API_VERSION
``` ```
## Include restarting ## Include restarting
Will also include restarting containers. Will also include restarting containers.
```text ```text
@ -186,6 +200,7 @@ Environment Variable: WATCHTOWER_INCLUDE_RESTARTING
``` ```
## Include stopped ## Include stopped
Will also include created and exited containers. Will also include created and exited containers.
```text ```text
@ -196,6 +211,7 @@ Environment Variable: WATCHTOWER_INCLUDE_STOPPED
``` ```
## Revive stopped ## Revive stopped
Start any stopped containers that have had their image updated. This argument is only usable with the `--include-stopped` argument. Start any stopped containers that have had their image updated. This argument is only usable with the `--include-stopped` argument.
```text ```text
@ -206,6 +222,7 @@ Environment Variable: WATCHTOWER_REVIVE_STOPPED
``` ```
## Poll interval ## Poll interval
Poll interval (in seconds). This value controls how frequently watchtower will poll for new images. Either `--schedule` or a poll interval can be defined, but not both. Poll interval (in seconds). This value controls how frequently watchtower will poll for new images. Either `--schedule` or a poll interval can be defined, but not both.
```text ```text
@ -216,6 +233,7 @@ Environment Variable: WATCHTOWER_POLL_INTERVAL
``` ```
## Filter by enable label ## Filter by enable label
Monitor and update containers that have a `com.centurylinklabs.watchtower.enable` label set to true. Monitor and update containers that have a `com.centurylinklabs.watchtower.enable` label set to true.
```text ```text
@ -226,11 +244,13 @@ Environment Variable: WATCHTOWER_LABEL_ENABLE
``` ```
## Filter by disable label ## Filter by disable label
__Do not__ Monitor and update containers that have `com.centurylinklabs.watchtower.enable` label set to false and __Do not__ Monitor and update containers that have `com.centurylinklabs.watchtower.enable` label set to false and
no `--label-enable` argument is passed. Note that only one or the other (targeting by enable label) can be no `--label-enable` argument is passed. Note that only one or the other (targeting by enable label) can be
used at the same time to target containers. used at the same time to target containers.
## Filter by disabling specific container names ## Filter by disabling specific container names
Monitor and update containers whose names are not in a given set of names. Monitor and update containers whose names are not in a given set of names.
This can be used to exclude specific containers, when setting labels is not an option. This can be used to exclude specific containers, when setting labels is not an option.
@ -244,6 +264,7 @@ Environment Variable: WATCHTOWER_DISABLE_CONTAINERS
``` ```
## Without updating containers ## Without updating containers
Will only monitor for new images, send notifications and invoke Will only monitor for new images, send notifications and invoke
the [pre-check/post-check hooks](https://watchtower.devcdn.net/lifecycle-hooks/), but will __not__ update the the [pre-check/post-check hooks](https://watchtower.devcdn.net/lifecycle-hooks/), but will __not__ update the
containers. containers.
@ -276,8 +297,10 @@ Environment Variable: WATCHTOWER_LABEL_TAKE_PRECEDENCE
``` ```
## Without restarting containers ## Without restarting containers
Do not restart containers after updating. This option can be useful when the start of the containers Do not restart containers after updating. This option can be useful when the start of the containers
is managed by an external system such as systemd. is managed by an external system such as systemd.
```text ```text
Argument: --no-restart Argument: --no-restart
Environment Variable: WATCHTOWER_NO_RESTART Environment Variable: WATCHTOWER_NO_RESTART
@ -286,6 +309,7 @@ Environment Variable: WATCHTOWER_NO_RESTART
``` ```
## Without pulling new images ## Without pulling new images
Do not pull new images. When this flag is specified, watchtower will not attempt to pull Do not pull new images. When this flag is specified, watchtower will not attempt to pull
new images from the registry. Instead it will only monitor the local image cache for changes. new images from the registry. Instead it will only monitor the local image cache for changes.
Use this option if you are building new images directly on the Docker host without pushing Use this option if you are building new images directly on the Docker host without pushing
@ -304,6 +328,7 @@ Note that no-pull can also be specified on a per-container basis with the
See [With label taking precedence over arguments](#With-label-taking-precedence-over-arguments) for behavior when both argument and label are set See [With label taking precedence over arguments](#With-label-taking-precedence-over-arguments) for behavior when both argument and label are set
## Without sending a startup message ## Without sending a startup message
Do not send a message after watchtower started. Otherwise there will be an info-level notification. Do not send a message after watchtower started. Otherwise there will be an info-level notification.
```text ```text
@ -324,6 +349,7 @@ Environment Variable: WATCHTOWER_RUN_ONCE
``` ```
## HTTP API Mode ## HTTP API Mode
Runs Watchtower in HTTP API mode, only allowing image updates to be triggered by an HTTP request. Runs Watchtower in HTTP API mode, only allowing image updates to be triggered by an HTTP request.
For details see [HTTP API](https://watchtower.devcdn.net/http-api-mode). For details see [HTTP API](https://watchtower.devcdn.net/http-api-mode).
@ -335,6 +361,7 @@ Environment Variable: WATCHTOWER_HTTP_API_UPDATE
``` ```
## HTTP API Token ## HTTP API Token
Sets an authentication token to HTTP API requests. Sets an authentication token to HTTP API requests.
Can also reference a file, in which case the contents of the file are used. Can also reference a file, in which case the contents of the file are used.
@ -346,6 +373,7 @@ Environment Variable: WATCHTOWER_HTTP_API_TOKEN
``` ```
## HTTP API periodic polls ## HTTP API periodic polls
Keep running periodic updates if the HTTP API mode is enabled, otherwise the HTTP API would prevent periodic polls. Keep running periodic updates if the HTTP API mode is enabled, otherwise the HTTP API would prevent periodic polls.
```text ```text
@ -356,6 +384,7 @@ Environment Variable: WATCHTOWER_HTTP_API_PERIODIC_POLLS
``` ```
## Filter by scope ## Filter by scope
Update containers that have a `com.centurylinklabs.watchtower.scope` label set with the same value as the given argument. Update containers that have a `com.centurylinklabs.watchtower.scope` label set with the same value as the given argument.
This enables [running multiple instances](https://watchtower.devcdn.net/running-multiple-instances). This enables [running multiple instances](https://watchtower.devcdn.net/running-multiple-instances).
@ -372,6 +401,7 @@ Environment Variable: WATCHTOWER_SCOPE
``` ```
## HTTP API Metrics ## HTTP API Metrics
Enables a metrics endpoint, exposing prometheus metrics via HTTP. See [Metrics](metrics.md) for details. Enables a metrics endpoint, exposing prometheus metrics via HTTP. See [Metrics](metrics.md) for details.
```text ```text
@ -382,6 +412,7 @@ Environment Variable: WATCHTOWER_HTTP_API_METRICS
``` ```
## Scheduling ## Scheduling
[Cron expression](https://pkg.go.dev/github.com/robfig/cron@v1.2.0?tab=doc#hdr-CRON_Expression_Format) in 6 fields (rather than the traditional 5) which defines when and how often to check for new images. Either `--interval` or the schedule expression [Cron expression](https://pkg.go.dev/github.com/robfig/cron@v1.2.0?tab=doc#hdr-CRON_Expression_Format) in 6 fields (rather than the traditional 5) which defines when and how often to check for new images. Either `--interval` or the schedule expression
can be defined, but not both. An example: `--schedule "0 0 4 * * *"` can be defined, but not both. An example: `--schedule "0 0 4 * * *"`
@ -393,6 +424,7 @@ Environment Variable: WATCHTOWER_SCHEDULE
``` ```
## Rolling restart ## Rolling restart
Restart one image at time instead of stopping and starting all at once. Useful in conjunction with lifecycle hooks Restart one image at time instead of stopping and starting all at once. Useful in conjunction with lifecycle hooks
to implement zero-downtime deploy. to implement zero-downtime deploy.
@ -404,6 +436,7 @@ Environment Variable: WATCHTOWER_ROLLING_RESTART
``` ```
## Wait until timeout ## Wait until timeout
Timeout before the container is forcefully stopped. When set, this option will change the default (`10s`) wait time to the given value. An example: `--stop-timeout 30s` will set the timeout to 30 seconds. Timeout before the container is forcefully stopped. When set, this option will change the default (`10s`) wait time to the given value. An example: `--stop-timeout 30s` will set the timeout to 30 seconds.
```text ```text
@ -455,10 +488,10 @@ Writes the session results to STDOUT using a stable, machine-readable format (in
Alias for: Alias for:
```text ```text
--notification-url logger:// --notification-url logger://
--notification-log-stdout --notification-log-stdout
--notification-report --notification-report
--notification-template porcelain.VERSION.summary-no-log --notification-template porcelain.VERSION.summary-no-log
Argument: --porcelain, -P Argument: --porcelain, -P
Environment Variable: WATCHTOWER_PORCELAIN Environment Variable: WATCHTOWER_PORCELAIN

12
docs/container-selection.md
View file

@ -1,11 +1,13 @@
# Container Selection
By default, watchtower will watch all containers. However, sometimes only some containers should be updated. By default, watchtower will watch all containers. However, sometimes only some containers should be updated.
There are two options: There are two options:
- **Fully exclude**: You can choose to exclude containers entirely from being watched by watchtower. - **Fully exclude**: You can choose to exclude containers entirely from being watched by watchtower.
- **Monitor only**: In this mode, watchtower checks for container updates, sends notifications and invokes the [pre-check/post-check hooks](https://watchtower.devcdn.net/lifecycle-hooks/) on the containers but does **not** perform the update. - **Monitor only**: In this mode, watchtower checks for container updates, sends notifications and invokes the [pre-check/post-check hooks](https://watchtower.devcdn.net/lifecycle-hooks/) on the containers but does **not** perform the update.
## Full Exclude ## Full Exclude
If you need to exclude some containers, set the _com.centurylinklabs.watchtower.enable_ label to `false`. For clarity this should be set **on the container(s)** you wish to be ignored, this is not set on watchtower. If you need to exclude some containers, set the _com.centurylinklabs.watchtower.enable_ label to `false`. For clarity this should be set **on the container(s)** you wish to be ignored, this is not set on watchtower.
@ -23,7 +25,6 @@ If you need to exclude some containers, set the _com.centurylinklabs.watchtower.
=== "docker-compose" === "docker-compose"
``` yaml ``` yaml
version: "3"
services: services:
someimage: someimage:
container_name: someimage container_name: someimage
@ -47,7 +48,6 @@ If instead you want to [only include containers with the enable label](https://w
=== "docker-compose" === "docker-compose"
``` yaml ``` yaml
version: "3"
services: services:
someimage: someimage:
container_name: someimage container_name: someimage
@ -78,4 +78,4 @@ Or, it can be specified as part of the `docker run` command line:
docker run -d --label=com.centurylinklabs.watchtower.monitor-only=true someimage docker run -d --label=com.centurylinklabs.watchtower.monitor-only=true someimage
``` ```
When the label is specified on a container, watchtower treats that container exactly as if [`WATCHTOWER_MONITOR_ONLY`](https://watchtower.devcdn.net/arguments/#without_updating_containers) was set, but the effect is limited to the individual container. When the label is specified on a container, watchtower treats that container exactly as if [`WATCHTOWER_MONITOR_ONLY`](https://watchtower.devcdn.net/arguments/#without_updating_containers) was set, but the effect is limited to the individual container.

4
docs/http-api-mode.md
View file

@ -1,3 +1,5 @@
# HTTP API Mode
Watchtower provides an HTTP API mode that enables an HTTP endpoint that can be requested to trigger container updating. The current available endpoint list is: Watchtower provides an HTTP API mode that enables an HTTP endpoint that can be requested to trigger container updating. The current available endpoint list is:
- `/v1/update` - triggers an update for all of the containers monitored by this Watchtower instance. - `/v1/update` - triggers an update for all of the containers monitored by this Watchtower instance.
@ -7,7 +9,7 @@ Watchtower provides an HTTP API mode that enables an HTTP endpoint that can be r
To enable this mode, use the flag `--http-api-update`. For example, in a Docker Compose config file: To enable this mode, use the flag `--http-api-update`. For example, in a Docker Compose config file:
```yaml ```yaml
version: '3'
services: services:
app-monitored-by-watchtower: app-monitored-by-watchtower:

3
docs/index.md
View file

@ -32,7 +32,7 @@
!!! note "Watchtower fork" !!! note "Watchtower fork"
This is a fork of the really nice project from [containrrr](https://github.com/containrrr) called [watchtower](https://github.com/containrrr/watchtower). This is a fork of the really nice project from [containrrr](https://github.com/containrrr) called [watchtower](https://github.com/containrrr/watchtower).
I am not the original author of this project. I just forked it to make some changes to it and keep it up-to-date as properly as I can. I am not the original author of this project. I just forked it to make some changes to it and keep it up-to-date as properly as I can.
Contributions, tips and hints are welcome. Just open an issue or a pull request. Please be aware that I am by no means a professional developer. I am just a Platform Engineer. Contributions, tips and hints are welcome. Just open an issue or a pull request. Please be aware that I am by no means a professional developer. I am just a Platform Engineer.
## Quick Start ## Quick Start
@ -54,7 +54,6 @@ the following command:
=== "docker-compose.yml" === "docker-compose.yml"
```yaml ```yaml
version: "3"
services: services:
watchtower: watchtower:
image: beatkind/watchtower image: beatkind/watchtower

3
docs/introduction.md
View file

@ -1,3 +1,5 @@
# Introduction
Watchtower is an application that will monitor your running Docker containers and watch for changes to the images that those containers were originally started from. If watchtower detects that an image has changed, it will automatically restart the container using the new image. Watchtower is an application that will monitor your running Docker containers and watch for changes to the images that those containers were originally started from. If watchtower detects that an image has changed, it will automatically restart the container using the new image.
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. 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.
@ -12,4 +14,3 @@ CONTAINER ID IMAGE STATUS PORTS
``` ```
Every day watchtower will pull the latest _centurylink/wetty-cli_ image and compare it to the one that was used to run the "wetty" container. If it sees that the image has changed it will stop/remove the "wetty" container and then restart it using the new image and the same `docker run` options that were used to start the container initially (in this case, that would include the `-p 8080:3000` port mapping). Every day watchtower will pull the latest _centurylink/wetty-cli_ image and compare it to the one that was used to run the "wetty" container. If it sees that the image has changed it will stop/remove the "wetty" container and then restart it using the new image and the same `docker run` options that were used to start the container initially (in this case, that would include the `-p 8080:3000` port mapping).

25
docs/lifecycle-hooks.md
View file

@ -1,10 +1,10 @@
## Executing commands before and after updating # Executing commands before and after updating
!!! note !!! note
These are shell commands executed with `sh`, and therefore require the container to provide the `sh` These are shell commands executed with `sh`, and therefore require the container to provide the `sh`
executable. executable.
> **DO NOTE**: If the container is not running then lifecycle hooks can not run and therefore > **DO NOTE**: If the container is not running then lifecycle hooks can not run and therefore
> the update is executed without running any lifecycle hooks. > the update is executed without running any lifecycle hooks.
It is possible to execute _pre/post\-check_ and _pre/post\-update_ commands It is possible to execute _pre/post\-check_ and _pre/post\-update_ commands
@ -19,14 +19,14 @@ This feature is disabled by default. To enable it, you need to set the option
`--enable-lifecycle-hooks` on the command line, or set the environment variable `--enable-lifecycle-hooks` on the command line, or set the environment variable
`WATCHTOWER_LIFECYCLE_HOOKS` to `true`. `WATCHTOWER_LIFECYCLE_HOOKS` to `true`.
### Specifying update commands ## Specifying update commands
The commands are specified using docker container labels, the following are currently available: The commands are specified using docker container labels, the following are currently available:
| Type | Docker Container Label | | Type | Docker Container Label |
| ----------- | ------------------------------------------------------ | | ----------- | ------------------------------------------------------ |
| Pre Check | `com.centurylinklabs.watchtower.lifecycle.pre-check` | | Pre Check | `com.centurylinklabs.watchtower.lifecycle.pre-check` |
| Pre Update | `com.centurylinklabs.watchtower.lifecycle.pre-update` | | Pre Update | `com.centurylinklabs.watchtower.lifecycle.pre-update` |
| Post Update | `com.centurylinklabs.watchtower.lifecycle.post-update` | | Post Update | `com.centurylinklabs.watchtower.lifecycle.post-update` |
| Post Check | `com.centurylinklabs.watchtower.lifecycle.post-check` | | Post Check | `com.centurylinklabs.watchtower.lifecycle.post-check` |
@ -34,7 +34,7 @@ These labels can be declared as instructions in a Dockerfile (with some example
the `docker run` command line: the `docker run` command line:
=== "Dockerfile" === "Dockerfile"
```docker ```docker
LABEL com.centurylinklabs.watchtower.lifecycle.pre-check="/sync.sh" LABEL com.centurylinklabs.watchtower.lifecycle.pre-check="/sync.sh"
LABEL com.centurylinklabs.watchtower.lifecycle.pre-update="/dump-data.sh" LABEL com.centurylinklabs.watchtower.lifecycle.pre-update="/dump-data.sh"
LABEL com.centurylinklabs.watchtower.lifecycle.post-update="/restore-data.sh" LABEL com.centurylinklabs.watchtower.lifecycle.post-update="/restore-data.sh"
@ -42,7 +42,7 @@ the `docker run` command line:
``` ```
=== "docker run" === "docker run"
```bash ```bash
docker run -d \ docker run -d \
--label=com.centurylinklabs.watchtower.lifecycle.pre-check="/sync.sh" \ --label=com.centurylinklabs.watchtower.lifecycle.pre-check="/sync.sh" \
--label=com.centurylinklabs.watchtower.lifecycle.pre-update="/dump-data.sh" \ --label=com.centurylinklabs.watchtower.lifecycle.pre-update="/dump-data.sh" \
@ -50,20 +50,21 @@ the `docker run` command line:
someimage --label=com.centurylinklabs.watchtower.lifecycle.post-check="/send-heartbeat.sh" \ someimage --label=com.centurylinklabs.watchtower.lifecycle.post-check="/send-heartbeat.sh" \
``` ```
### Timeouts ## Timeouts
The timeout for all lifecycle commands is 60 seconds. After that, a timeout will The timeout for all lifecycle commands is 60 seconds. After that, a timeout will
occur, forcing Watchtower to continue the update loop. occur, forcing Watchtower to continue the update loop.
#### Pre- or Post-update timeouts ### Pre- or Post-update timeouts
For the `pre-update` or `post-update` lifecycle command, it is possible to override this timeout to For the `pre-update` or `post-update` lifecycle command, it is possible to override this timeout to
allow the script to finish before forcefully killing it. This is done by adding the allow the script to finish before forcefully killing it. This is done by adding the
label `com.centurylinklabs.watchtower.lifecycle.pre-update-timeout` or post-update-timeout respectively followed by label `com.centurylinklabs.watchtower.lifecycle.pre-update-timeout` or post-update-timeout respectively followed by
the timeout expressed in minutes. the timeout expressed in minutes.
If the label value is explicitly set to `0`, the timeout will be disabled. If the label value is explicitly set to `0`, the timeout will be disabled.
### Execution failure ## Execution failure
The failure of a command to execute, identified by an exit code different than The failure of a command to execute, identified by an exit code different than
0 or 75 (EX_TEMPFAIL), will not prevent watchtower from updating the container. Only an error 0 or 75 (EX_TEMPFAIL), will not prevent watchtower from updating the container. Only an error

2
docs/linked-containers.md
View file

@ -1,3 +1,5 @@
# Linked Containers
Watchtower will detect if there are links between any of the running containers and ensures that things are stopped/started in a way that won't break any of the links. If an update is detected for one of the dependencies in a group of linked containers, watchtower will stop and start all of the containers in the correct order so that the application comes back up correctly. Watchtower will detect if there are links between any of the running containers and ensures that things are stopped/started in a way that won't break any of the links. If an update is detected for one of the dependencies in a group of linked containers, watchtower will stop and start all of the containers in the correct order so that the application comes back up correctly.
For example, imagine you were running a _mysql_ container and a _wordpress_ container which had been linked to the _mysql_ container. If watchtower were to detect that the _mysql_ container required an update, it would first shut down the linked _wordpress_ container followed by the _mysql_ container. When restarting the containers it would handle _mysql_ first and then _wordpress_ to ensure that the link continued to work. For example, imagine you were running a _mysql_ container and a _wordpress_ container which had been linked to the _mysql_ container. If watchtower were to detect that the _mysql_ container required an update, it would first shut down the linked _wordpress_ container followed by the _mysql_ container. When restarting the containers it would handle _mysql_ first and then _wordpress_ to ensure that the link continued to work.

4
docs/metrics.md
View file

@ -1,3 +1,5 @@
# Watchtower Metrics
!!! warning "Experimental feature" !!! warning "Experimental feature"
This feature was added in v1.0.4 and is still considered experimental. If you notice any strange behavior, please raise This feature was added in v1.0.4 and is still considered experimental. If you notice any strange behavior, please raise
a ticket in the repository issues. a ticket in the repository issues.
@ -9,7 +11,7 @@ as well as creating a port mapping for your container for port `8080`.
The metrics API endpoint is `/v1/metrics`. The metrics API endpoint is `/v1/metrics`.
## Available Metrics ## Available Metrics
| Name | Type | Description | | Name | Type | Description |
| ------------------------------- | ------- | --------------------------------------------------------------------------- | | ------------------------------- | ------- | --------------------------------------------------------------------------- |

7
docs/notifications.md
View file

@ -144,7 +144,7 @@ Example using a custom report template that always sends a session report after
=== "docker-compose" === "docker-compose"
``` yaml ``` yaml
version: "3"
services: services:
watchtower: watchtower:
image: beatkind/watchtower image: beatkind/watchtower
@ -206,7 +206,7 @@ If watchtower is started with `notify-upgrade` as it's first argument, it will g
=== "docker-compose.yml" === "docker-compose.yml"
```yaml ```yaml
version: "3"
services: services:
watchtower: watchtower:
image: beatkind/watchtower image: beatkind/watchtower
@ -234,7 +234,7 @@ You can then copy this file from the container (a message with the full command
=== "docker-compose.yml" === "docker-compose.yml"
```yaml ```yaml
version: "3"
services: services:
watchtower: watchtower:
image: beatkind/watchtower image: beatkind/watchtower
@ -283,7 +283,6 @@ The following example assumes, that your domain is called `your-domain.com` and
Example including an SMTP relay: Example including an SMTP relay:
```yaml ```yaml
version: '3.8'
services: services:
watchtower: watchtower:
image: beatkind/watchtower:latest image: beatkind/watchtower:latest

46
docs/private-registries.md
View file

@ -1,6 +1,8 @@
# Private Registries
Watchtower supports private Docker image registries. In many cases, accessing a private registry Watchtower supports private Docker image registries. In many cases, accessing a private registry
requires a valid username and password (i.e., _credentials_). In order to operate in such an requires a valid username and password (i.e., _credentials_). In order to operate in such an
environment, watchtower needs to know the credentials to access the registry. environment, watchtower needs to know the credentials to access the registry.
The credentials can be provided to watchtower in a configuration file called `config.json`. The credentials can be provided to watchtower in a configuration file called `config.json`.
There are two ways to generate this configuration file: There are two ways to generate this configuration file:
@ -8,7 +10,8 @@ There are two ways to generate this configuration file:
* The configuration file can be created manually. * The configuration file can be created manually.
* Call `docker login <REGISTRY_NAME>` and share the resulting configuration file. * Call `docker login <REGISTRY_NAME>` and share the resulting configuration file.
### Create the configuration file manually ## Create the configuration file manually
Create a new configuration file with the following syntax and a base64 encoded username and Create a new configuration file with the following syntax and a base64 encoded username and
password `auth` string: password `auth` string:
@ -31,7 +34,7 @@ password `auth` string:
In this special case, the registry domain does not have to be specified In this special case, the registry domain does not have to be specified
in `docker run` or `docker-compose`. Like Docker, Watchtower will use the in `docker run` or `docker-compose`. Like Docker, Watchtower will use the
Docker Hub registry and its credentials when no registry domain is specified. Docker Hub registry and its credentials when no registry domain is specified.
<sub>Watchtower will recognize credentials with `<REGISTRY_NAME>` `index.docker.io`, <sub>Watchtower will recognize credentials with `<REGISTRY_NAME>` `index.docker.io`,
but the Docker CLI will not.</sub> but the Docker CLI will not.</sub>
@ -40,7 +43,7 @@ password `auth` string:
in both `config.json` and the `docker run` command or `docker-compose` file. in both `config.json` and the `docker run` command or `docker-compose` file.
Valid hosts are `localhost[:PORT]`, `HOST:PORT`, Valid hosts are `localhost[:PORT]`, `HOST:PORT`,
or any multi-part `domain.name` or IP-address with or without a port. or any multi-part `domain.name` or IP-address with or without a port.
Examples: Examples:
* `localhost` -> `localhost/myimage` * `localhost` -> `localhost/myimage`
* `127.0.0.1` -> `127.0.0.1/myimage:mytag` * `127.0.0.1` -> `127.0.0.1/myimage:mytag`
@ -66,7 +69,7 @@ When the watchtower Docker container is started, the created configuration file
docker run [...] -v <PATH>/config.json:/config.json beatkind/watchtower docker run [...] -v <PATH>/config.json:/config.json beatkind/watchtower
``` ```
### Share the Docker configuration file ## Share the Docker configuration file
To pull an image from a private registry, `docker login` needs to be called first, to get access To pull an image from a private registry, `docker login` needs to be called first, to get access
to the registry. The provided credentials are stored in a configuration file called `<PATH_TO_HOME_DIR>/.docker/config.json`. to the registry. The provided credentials are stored in a configuration file called `<PATH_TO_HOME_DIR>/.docker/config.json`.
@ -92,14 +95,15 @@ services:
... ...
``` ```
#### Docker Config path ### Docker Config path
By default, watchtower will look for the `config.json` file in `/`, but this can be changed by setting the `DOCKER_CONFIG` environment variable to the directory path where your config is located. This is useful for setups where the config.json file is changed while the watchtower instance is running, as the changes will not be picked up for a mounted file if the inode changes. By default, watchtower will look for the `config.json` file in `/`, but this can be changed by setting the `DOCKER_CONFIG` environment variable to the directory path where your config is located. This is useful for setups where the config.json file is changed while the watchtower instance is running, as the changes will not be picked up for a mounted file if the inode changes.
Example usage: Example usage:
```yaml ```yaml
version: "3.4" version: "3.4"
services: services:
watchtower: watchtower:
image: beatkind/watchtower image: beatkind/watchtower
environment: environment:
@ -110,6 +114,7 @@ services:
``` ```
## Credential helpers ## Credential helpers
Some private Docker registries (the most prominent probably being AWS ECR) use non-standard ways of authentication. Some private Docker registries (the most prominent probably being AWS ECR) use non-standard ways of authentication.
To be able to use this together with watchtower, we need to use a credential helper. To be able to use this together with watchtower, we need to use a credential helper.
@ -117,6 +122,7 @@ To keep the image size small we've decided to not include any helpers in the wat
helper in a separate container and mount it using volumes. helper in a separate container and mount it using volumes.
### Example ### Example
Example implementation for use with [amazon-ecr-credential-helper](https://github.com/awslabs/amazon-ecr-credential-helper): Example implementation for use with [amazon-ecr-credential-helper](https://github.com/awslabs/amazon-ecr-credential-helper):
Use the dockerfile below to build the [amazon-ecr-credential-helper](https://github.com/awslabs/amazon-ecr-credential-helper), Use the dockerfile below to build the [amazon-ecr-credential-helper](https://github.com/awslabs/amazon-ecr-credential-helper),
@ -125,30 +131,30 @@ in a volume that may be mounted onto your watchtower container.
1. Create the Dockerfile (contents below): 1. Create the Dockerfile (contents below):
```Dockerfile ```Dockerfile
FROM golang:1.20 FROM golang:1.20
ENV GO111MODULE off ENV GO111MODULE off
ENV CGO_ENABLED 0 ENV CGO_ENABLED 0
ENV REPO github.com/awslabs/amazon-ecr-credential-helper/ecr-login/cli/docker-credential-ecr-login ENV REPO github.com/awslabs/amazon-ecr-credential-helper/ecr-login/cli/docker-credential-ecr-login
RUN go get -u $REPO RUN go get -u $REPO
RUN rm /go/bin/docker-credential-ecr-login RUN rm /go/bin/docker-credential-ecr-login
RUN go build \ RUN go build \
-o /go/bin/docker-credential-ecr-login \ -o /go/bin/docker-credential-ecr-login \
/go/src/$REPO /go/src/$REPO
WORKDIR /go/bin/ WORKDIR /go/bin/
``` ```
2. Use the following commands to build the aws-ecr-dock-cred-helper and store it's output in a volume: 2. Use the following commands to build the aws-ecr-dock-cred-helper and store it's output in a volume:
```bash ```bash
# Create a volume to store the command (once built) # Create a volume to store the command (once built)
docker volume create helper docker volume create helper
# Build the container # Build the container
docker build -t aws-ecr-dock-cred-helper . docker build -t aws-ecr-dock-cred-helper .
# Build the command and store it in the new volume in the /go/bin directory. # Build the command and store it in the new volume in the /go/bin directory.
docker run -d --rm --name aws-cred-helper \ docker run -d --rm --name aws-cred-helper \
--volume helper:/go/bin aws-ecr-dock-cred-helper --volume helper:/go/bin aws-ecr-dock-cred-helper
@ -188,20 +194,20 @@ in a volume that may be mounted onto your watchtower container.
- PATH=$PATH:/go/bin - PATH=$PATH:/go/bin
- AWS_REGION=us-west-1 - AWS_REGION=us-west-1
volumes: volumes:
helper: helper:
external: true external: true
``` ```
A few additional notes: A few additional notes:
1. With docker-compose the volume (helper, in this case) MUST be set to `external: true`, otherwise docker-compose 1. With docker-compose the volume (helper, in this case) MUST be set to `external: true`, otherwise docker-compose
will preface it with the directory name. will preface it with the directory name.
2. Note that "credsStore" : "ecr-login" is needed - and in theory if you have that you can remove the 2. Note that "credsStore" : "ecr-login" is needed - and in theory if you have that you can remove the
credHelpers section credHelpers section
3. I have this running on an EC2 instance that has credentials assigned to it - so no keys are needed; however, 3. I have this running on an EC2 instance that has credentials assigned to it - so no keys are needed; however,
you may need to include the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables as well. you may need to include the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables as well.
4. An alternative to adding the various variables is to create a ~/.aws/config and ~/.aws/credentials files and 4. An alternative to adding the various variables is to create a ~/.aws/config and ~/.aws/credentials files and
place the settings there, then mount the ~/.aws directory to / in the container. place the settings there, then mount the ~/.aws directory to / in the container.

2
docs/remote-hosts.md
View file

@ -1,3 +1,5 @@
# Remote Docker Hosts
By default, watchtower is set-up to monitor the local Docker daemon (the same daemon running the watchtower container itself). However, it is possible to configure watchtower to monitor a remote Docker endpoint. When starting the watchtower container you can specify a remote Docker endpoint with either the `--host` flag or the `DOCKER_HOST` environment variable: By default, watchtower is set-up to monitor the local Docker daemon (the same daemon running the watchtower container itself). However, it is possible to configure watchtower to monitor a remote Docker endpoint. When starting the watchtower container you can specify a remote Docker endpoint with either the `--host` flag or the `DOCKER_HOST` environment variable:
```bash ```bash

10
docs/running-multiple-instances.md
View file

@ -1,4 +1,4 @@
By default, Watchtower will clean up other instances and won't allow multiple instances running on the same Docker host or swarm. It is possible to override this behavior by defining a [scope](https://watchtower.devcdn.net/arguments/#filter_by_scope) to each running instance. By default, Watchtower will clean up other instances and won't allow multiple instances running on the same Docker host or swarm. It is possible to override this behavior by defining a [scope](https://watchtower.devcdn.net/arguments/#filter_by_scope) to each running instance.
!!! note !!! note
- Multiple instances can't run with the same scope; - Multiple instances can't run with the same scope;
@ -10,7 +10,7 @@ To define an instance monitoring scope, use the `--scope` argument or the `WATCH
For example, in a Docker Compose config file: For example, in a Docker Compose config file:
```yaml ```yaml
version: '3'
services: services:
app-with-scope: app-with-scope:
@ -21,7 +21,7 @@ services:
image: beatkind/watchtower image: beatkind/watchtower
volumes: [ "/var/run/docker.sock:/var/run/docker.sock" ] volumes: [ "/var/run/docker.sock:/var/run/docker.sock" ]
command: --interval 30 --scope myscope command: --interval 30 --scope myscope
labels: [ "com.centurylinklabs.watchtower.scope=myscope" ] labels: [ "com.centurylinklabs.watchtower.scope=myscope" ]
unscoped-app-a: unscoped-app-a:
image: myapps/app-a image: myapps/app-a
@ -29,11 +29,11 @@ services:
unscoped-app-b: unscoped-app-b:
image: myapps/app-b image: myapps/app-b
labels: [ "com.centurylinklabs.watchtower.scope=none" ] labels: [ "com.centurylinklabs.watchtower.scope=none" ]
unscoped-app-c: unscoped-app-c:
image: myapps/app-b image: myapps/app-b
labels: [ "com.centurylinklabs.watchtower.scope=" ] labels: [ "com.centurylinklabs.watchtower.scope=" ]
unscoped-watchtower: unscoped-watchtower:
image: beatkind/watchtower image: beatkind/watchtower
volumes: [ "/var/run/docker.sock:/var/run/docker.sock" ] volumes: [ "/var/run/docker.sock:/var/run/docker.sock" ]

2
docs/secure-connections.md
View file

@ -1,3 +1,5 @@
# Secure Connections
Watchtower is also capable of connecting to Docker endpoints which are protected by SSL/TLS. If you've used _docker-machine_ to provision your remote Docker host, you simply need to volume mount the certificates generated by _docker-machine_ into the watchtower container and optionally specify `--tlsverify` flag. Watchtower is also capable of connecting to Docker endpoints which are protected by SSL/TLS. If you've used _docker-machine_ to provision your remote Docker host, you simply need to volume mount the certificates generated by _docker-machine_ into the watchtower container and optionally specify `--tlsverify` flag.
The _docker-machine_ certificates for a particular host can be located by executing the `docker-machine env` command for the desired host (note the values for the `DOCKER_HOST` and `DOCKER_CERT_PATH` environment variables that are returned from this command). The directory containing the certificates for the remote host needs to be mounted into the watchtower container at _/etc/ssl/docker_. The _docker-machine_ certificates for a particular host can be located by executing the `docker-machine env` command for the desired host (note the values for the `DOCKER_HOST` and `DOCKER_CERT_PATH` environment variables that are returned from this command). The directory containing the certificates for the remote host needs to be mounted into the watchtower container at _/etc/ssl/docker_.

2
docs/stop-signals.md
View file

@ -1,3 +1,5 @@
# Stop signals
When watchtower detects that a running container needs to be updated it will stop the container by sending it a SIGTERM signal. When watchtower detects that a running container needs to be updated it will stop the container by sending it a SIGTERM signal.
If your container should be shutdown with a different signal you can communicate this to watchtower by setting a label named _com.centurylinklabs.watchtower.stop-signal_ with the value of the desired signal. If your container should be shutdown with a different signal you can communicate this to watchtower by setting a label named _com.centurylinklabs.watchtower.stop-signal_ with the value of the desired signal.

8
docs/updating.md
View file

@ -1,6 +1,6 @@
## Updating Watchtower # Updating Watchtower
If watchtower is monitoring the same Docker daemon under which the watchtower container itself is running (i.e. if you If watchtower is monitoring the same Docker daemon under which the watchtower container itself is running (i.e. if you
volume-mounted `/var/run/docker.sock` into the watchtower container) then it has the ability to update itself. volume-mounted `/var/run/docker.sock` into the watchtower container) then it has the ability to update itself.
If a new version of the `beatkind/watchtower` image is pushed to the Docker Hub, your watchtower will pull down the If a new version of the `beatkind/watchtower` image is pushed to the Docker Hub, your watchtower will pull down the
new image and restart itself automatically. new image and restart itself automatically.

8
docs/usage-overview.md
View file

@ -1,3 +1,5 @@
# Usage
Watchtower is itself packaged as a Docker container so installation is as simple as pulling the `beatkind/watchtower` image. If you are using ARM based architecture, pull the appropriate `beatkind/watchtower:armhf-<tag>` image from the [beatkind Docker Hub](https://hub.docker.com/r/beatkind/watchtower/tags/). Watchtower is itself packaged as a Docker container so installation is as simple as pulling the `beatkind/watchtower` image. If you are using ARM based architecture, pull the appropriate `beatkind/watchtower:armhf-<tag>` image from the [beatkind Docker Hub](https://hub.docker.com/r/beatkind/watchtower/tags/).
Since the watchtower code needs to interact with the Docker API in order to monitor the running containers, you need to mount _/var/run/docker.sock_ into the container with the `-v` flag when you run it. Since the watchtower code needs to interact with the Docker API in order to monitor the running containers, you need to mount _/var/run/docker.sock_ into the container with the `-v` flag when you run it.
@ -41,8 +43,8 @@ docker run -d \
If you mount `config.json` in the manner above, changes from the host system will (generally) not be propagated to the If you mount `config.json` in the manner above, changes from the host system will (generally) not be propagated to the
running container. Mounting files into the Docker daemon uses bind mounts, which are based on inodes. Most running container. Mounting files into the Docker daemon uses bind mounts, which are based on inodes. Most
applications (including `docker login` and `vim`) will not directly edit the file, but instead make a copy and replace applications (including `docker login` and `vim`) will not directly edit the file, but instead make a copy and replace
the original file, which results in a new inode which in turn _breaks_ the bind mount. the original file, which results in a new inode which in turn _breaks_ the bind mount.
**As a workaround**, you can create a symlink to your `config.json` file and then mount the symlink in the container. **As a workaround**, you can create a symlink to your `config.json` file and then mount the symlink in the container.
The symlinked file will always have the same inode, which keeps the bind mount intact and will ensure changes The symlinked file will always have the same inode, which keeps the bind mount intact and will ensure changes
to the original file are propagated to the running container (regardless of the inode of the source file!). to the original file are propagated to the running container (regardless of the inode of the source file!).
@ -52,7 +54,7 @@ from a private repo on the GitHub Registry and monitors it with watchtower. Note
to 30s rather than the default 24 hours. to 30s rather than the default 24 hours.
```yaml ```yaml
version: "3"
services: services:
cavo: cavo:
image: ghcr.io/<org>/<image>:<tag> image: ghcr.io/<org>/<image>:<tag>

2
mkdocs.yml
View file

@ -1,5 +1,5 @@
site_name: Watchtower site_name: Watchtower
site_url: https://containrrr.dev/watchtower/ site_url: https://watchtower.devcdn.net/
repo_url: https://github.com/beatkind/watchtower/ repo_url: https://github.com/beatkind/watchtower/
edit_uri: edit/main/docs/ edit_uri: edit/main/docs/
theme: theme: