@ -30,7 +30,7 @@ When no arguments are specified, watchtower will monitor all running containers.
## Help
## Help
Shows documentation about the supported flags.
Shows documentation about the supported flags.
```
```text
Argument: --help
Argument: --help
Environment Variable: N/A
Environment Variable: N/A
Type: N/A
Type: N/A
@ -41,7 +41,7 @@ Environment Variable: N/A
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`
```
```text
Argument: N/A
Argument: N/A
Environment Variable: TZ
Environment Variable: TZ
Type: String
Type: String
@ -51,7 +51,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.
Removes attached volumes after updating. When this flag is specified, watchtower will remove all attached volumes from the container before restarting with a new image. Use this option to force new volumes to be populated as containers are updated.
Removes attached volumes after updating. When this flag is specified, watchtower will remove all attached volumes from the container before restarting with a new image. Use this option to force new volumes to be populated as containers are updated.
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.
**Do not** 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 used at the same time to target containers.
__Do not__ 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
used at the same time to target containers.
## Without updating containers
## Without updating containers
Will only monitor for new images, send notifications and invoke the [pre-check/post-check hooks](https://containrrr.dev/watchtower/lifecycle-hooks/), but will **not** update the containers.
Will only monitor for new images, send notifications and invoke
the [pre-check/post-check hooks](https://containrrr.dev/watchtower/lifecycle-hooks/), but will __not__ update the
containers.
> **⚠️ Please note**
!!! note Due to Docker API limitations the latest image will still be pulled from the registry.
>
The HEAD digest checks allows watchtower to skip pulling when there are no changes, but to know _what_ has changed it
> Due to Docker API limitations the latest image will still be pulled from the registry.
will still do a pull whenever the repository digest doesn't match the local image digest.
```
```text
Argument: --monitor-only
Argument: --monitor-only
Environment Variable: WATCHTOWER_MONITOR_ONLY
Environment Variable: WATCHTOWER_MONITOR_ONLY
Type: Boolean
Type: Boolean
@ -190,7 +194,7 @@ Note that monitor-only can also be specified on a per-container basis with the `
## 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
Argument: --no-restart
Argument: --no-restart
Environment Variable: WATCHTOWER_NO_RESTART
Environment Variable: WATCHTOWER_NO_RESTART
Type: Boolean
Type: Boolean
@ -203,7 +207,7 @@ new images from the registry. Instead it will only monitor the local image cache
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
Runs Watchtower in HTTP API mode, only allowing image updates to be triggered by an HTTP request. For details see [HTTP API](https://containrrr.github.io/watchtower/http-api-mode).
Runs Watchtower in HTTP API mode, only allowing image updates to be triggered by an HTTP request.
For details see [HTTP API](https://containrrr.github.io/watchtower/http-api-mode).
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://containrrr.github.io/watchtower/running-multiple-instances).
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://containrrr.github.io/watchtower/running-multiple-instances).
[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 * * *"`
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.
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:
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
Watchtower can send notifications when containers are updated. Notifications are sent via hooks in the logging system, [logrus](http://github.com/sirupsen/logrus).
Watchtower can send notifications when containers are updated. Notifications are sent via hooks in the logging
The types of notifications to send are set by passing a comma-separated list of values to the `--notifications` option (or corresponding environment variable `WATCHTOWER_NOTIFICATIONS`), which has the following valid values:
system, [logrus](http://github.com/sirupsen/logrus). The types of notifications to send are set by passing a
comma-separated list of values to the `--notifications` option
(or corresponding environment variable `WATCHTOWER_NOTIFICATIONS`), which has the following valid values:
- `email` to send notifications via e-mail
- `email` to send notifications via e-mail
- `slack` to send notifications through a Slack webhook
- `slack` to send notifications through a Slack webhook
@ -9,11 +11,16 @@ The types of notifications to send are set by passing a comma-separated list of
- `gotify` to send notifications via Gotify
- `gotify` to send notifications via Gotify
- `shoutrrr` to send notifications via [containrrr/shoutrrr](https://github.com/containrrr/shoutrrr)
- `shoutrrr` to send notifications via [containrrr/shoutrrr](https://github.com/containrrr/shoutrrr)
> There is currently a [bug](https://github.com/spf13/viper/issues/380) in Viper, which prevents comma-separated slices to be used when using the environment variable. A workaround is available where we instead put quotes around the environment variable value and replace the commas with spaces, as `WATCHTOWER_NOTIFICATIONS="slack msteams"`
!!! note "Using multiple notifications with environment variables"
There is currently a bug in Viper (https://github.com/spf13/viper/issues/380), which prevents comma-separated slices to
> If you're a `docker-compose` user, make sure to specify environment variables' values in your `.yml` file without double quotes (`"`).
be used when using the environment variable.
>
A workaround is available where we instead put quotes around the environment variable value and replace the commas with
> This prevents unexpected errors when watchtower starts.
spaces:
```
WATCHTOWER_NOTIFICATIONS="slack msteams"
```
If you're a `docker-compose` user, make sure to specify environment variables' values in your `.yml` file without double
quotes (`"`). This prevents unexpected errors when watchtower starts.
## Settings
## Settings
@ -60,7 +67,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'
version: '3.8'
services:
services:
watchtower:
watchtower:
@ -117,8 +123,6 @@ By default, watchtower will send messages under the name `watchtower`, you can c
Other, optional, variables include:
Other, optional, variables include:
- `--notification-slack-channel` (env. `WATCHTOWER_NOTIFICATION_SLACK_CHANNEL`): A string which overrides the webhook's default channel. Example: #my-custom-channel.
- `--notification-slack-channel` (env. `WATCHTOWER_NOTIFICATION_SLACK_CHANNEL`): A string which overrides the webhook's default channel. Example: #my-custom-channel.
- `--notification-slack-icon-emoji` (env. `WATCHTOWER_NOTIFICATION_SLACK_ICON_EMOJI`): An [emoji code](https://www.webpagefx.com/tools/emoji-cheat-sheet/) string to use in place of the default icon.
- `--notification-slack-icon-url` (env. `WATCHTOWER_NOTIFICATION_SLACK_ICON_URL`): An icon image URL string to use in place of the default icon.
@ -179,16 +181,25 @@ To send notifications via shoutrrr, the following command-line options, or their
- `--notification-url` (env. `WATCHTOWER_NOTIFICATION_URL`): The shoutrrr service URL to be used.
- `--notification-url` (env. `WATCHTOWER_NOTIFICATION_URL`): The shoutrrr service URL to be used.
Go to [containrrr.github.io/shoutrrr/services/overview](https://containrrr.github.io/shoutrrr/services/overview) to learn more about the different service URLs you can use.
Go to [containrrr.github.io/shoutrrr/services/overview](https://containrrr.github.io/shoutrrr/services/overview) to
You can define multiple services by space separating the URLs. (See example below)
learn more about the different service URLs you can use. You can define multiple services by space separating the
URLs. (See example below)
You can customize the message posted by setting a template.
You can customize the message posted by setting a template.
- `--notification-template` (env. `WATCHTOWER_NOTIFICATION_TEMPLATE`): The template used for the message.
- `--notification-template` (env. `WATCHTOWER_NOTIFICATION_TEMPLATE`): The template used for the message.
The template is a Go [template](https://golang.org/pkg/text/template/) and the you format a list of [log entries](https://pkg.go.dev/github.com/sirupsen/logrus?tab=doc#Entry).
The template is a Go [template](https://golang.org/pkg/text/template/) and that format a list
of [log entries](https://pkg.go.dev/github.com/sirupsen/logrus?tab=doc#Entry).
The default value if not set is `{{range .}}{{.Message}}{{println}}{{end}}`. The example below uses a template that also
outputs timestamp and log level.
The default value if not set is `{{range .}}{{.Message}}{{println}}{{end}}`. The example below uses a template that also outputs timestamp and log level.
!!! tip "Custom date format"
If you want to adjust the date/time format it must show how the
[reference time](https://golang.org/pkg/time/#pkg-constants) (_Mon Jan 2 15:04:05 MST 2006_) would be displayed in your
custom format.
i.e. The day of the year has to be 1, the month has to be 2 (february), the hour 3 (or 15 for 24h time) etc.
> NOTE: 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 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. **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 to the original file are propagated to the running container (regardless of the inode of the source file!).
!!! note "Changes to config.json while running"
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
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.
**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
to the original file are propagated to the running container (regardless of the inode of the source file!).
If you mount the config file as described above, be sure to also prepend the URL for the registry when starting up your watched image (you can omit the https://). Here is a complete docker-compose.yml file that starts up a docker container from a private repo at Docker Hub and monitors it with watchtower. Note the command argument changing the interval to 30s rather than the default 24 hours.
If you mount the config file as described above, be sure to also prepend the URL for the registry when starting up your
watched image (you can omit the https://). Here is a complete docker-compose.yml file that starts up a docker container
from a private repo at Docker Hub and monitors it with watchtower. Note the command argument changing the interval to
nils måsén
3 years ago
committed by