-
-
-
+
+
+ # Watchtower
+
A process for automating Docker container base image updates.
-
-
- 
-
-
- 
-
-
- 
-
-
- 
-
-
- 
-
-
- 
-
-
- 
-
-
-
-> ### β οΈ Help needed
->
-> As I [@simskij](https://github.com/simskij) currently am the sole maintainer of watchtower, i'm finding it a bit hard to keep up with all issues and pull requests. Interested in helping out with triage, troubleshooting and issue handling? Let me know on gitter!
+
+ [](https://circleci.com/gh/containrrr/watchtower)
+ [](https://codecov.io/gh/containrrr/watchtower)
+ [](https://godoc.org/github.com/containrrr/watchtower)
+ [](https://goreportcard.com/report/github.com/containrrr/watchtower)
+ [](https://github.com/containrrr/watchtower/releases)
+ [](https://www.apache.org/licenses/LICENSE-2.0)
+ [](https://www.codacy.com/gh/containrrr/watchtower/dashboard?utm_source=github.com&utm_medium=referral&utm_content=containrrr/watchtower&utm_campaign=Badge_Grade)
+ [](#contributors)
+ [](https://hub.docker.com/r/containrrr/watchtower)
+
+ 
+
+
+ 
+
-
-
-
-
- 
-
-
-
-
-
+
+ 
## 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:
+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 -d \
+=== "docker run"
+
+ ```bash
+ $ docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
containrrr/watchtower
-```
\ No newline at end of file
+ ```
+
+=== "docker-compose.yml"
+
+ ```yaml
+ version: "3"
+ services:
+ watchtower:
+ image: containrrr/watchtower
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
+ ```
diff --git a/docs/introduction.md b/docs/introduction.md
index 9e0f5fe..cbbc3a3 100644
--- a/docs/introduction.md
+++ b/docs/introduction.md
@@ -4,12 +4,12 @@ With watchtower you can update the running version of your containerized app sim
For example, let's say you were running watchtower along with an instance of _centurylink/wetty-cli_ image:
-```bash
+```text
$ docker ps
CONTAINER ID IMAGE STATUS PORTS NAMES
967848166a45 centurylink/wetty-cli Up 10 minutes 0.0.0.0:8080->3000/tcp wetty
6cc4d2a9d1a5 containrrr/watchtower Up 15 minutes watchtower
```
-Every few minutes 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).
diff --git a/docs/lifecycle-hooks.md b/docs/lifecycle-hooks.md
index 071726c..0c1e4e0 100644
--- a/docs/lifecycle-hooks.md
+++ b/docs/lifecycle-hooks.md
@@ -1,15 +1,19 @@
## Executing commands before and after updating
-> **DO NOTE**: These are shell commands executed with `sh`, and therefore require the
-> container to provide the `sh` executable.
+!!! note
+ These are shell commands executed with `sh`, and therefore require the container to provide the `sh`
+ executable.
+
+> **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.
It is possible to execute _pre/post\-check_ and _pre/post\-update_ commands
**inside** every container updated by watchtower.
-- The _pre-check_ command is executed for each container prior to every update cycle.
-- The _pre-update_ command is executed before stopping the container when an update is about to start.
-- The _post-update_ command is executed after restarting the updated container
-- The _post-check_ command is executed for each container post every update cycle.
+- The _pre-check_ command is executed for each container prior to every update cycle.
+- The _pre-update_ command is executed before stopping the container when an update is about to start.
+- The _post-update_ command is executed after restarting the updated container
+- The _post-check_ command is executed for each container post every update cycle.
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
@@ -26,28 +30,41 @@ The commands are specified using docker container labels, the following are curr
| Post Update | `com.centurylinklabs.watchtower.lifecycle.post-update` |
| Post Check | `com.centurylinklabs.watchtower.lifecycle.post-check` |
-These labels can be declared as instructions in a Dockerfile (with some example .sh files):
+These labels can be declared as instructions in a Dockerfile (with some example .sh files) or be specified as part of
+the `docker run` command line:
-```docker
-LABEL com.centurylinklabs.watchtower.lifecycle.pre-check="/sync.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-check="/send-heartbeat.sh"
-```
+=== "Dockerfile"
+ ```docker
+ LABEL com.centurylinklabs.watchtower.lifecycle.pre-check="/sync.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-check="/send-heartbeat.sh"
+ ```
-Or be specified as part of the `docker run` command line:
+=== "docker run"
+ ```bash
+ docker run -d \
+ --label=com.centurylinklabs.watchtower.lifecycle.pre-check="/sync.sh" \
+ --label=com.centurylinklabs.watchtower.lifecycle.pre-update="/dump-data.sh" \
+ --label=com.centurylinklabs.watchtower.lifecycle.post-update="/restore-data.sh" \
+ someimage --label=com.centurylinklabs.watchtower.lifecycle.post-check="/send-heartbeat.sh" \
+ ```
-```bash
-docker run -d \
- --label=com.centurylinklabs.watchtower.lifecycle.pre-check="/sync.sh" \
- --label=com.centurylinklabs.watchtower.lifecycle.pre-update="/dump-data.sh" \
- --label=com.centurylinklabs.watchtower.lifecycle.post-update="/restore-data.sh" \
- someimage
- --label=com.centurylinklabs.watchtower.lifecycle.post-check="/send-heartbeat.sh" \
-```
+### Timeouts
+The timeout for all lifecycle commands is 60 seconds. After that, a timeout will
+occur, forcing Watchtower to continue the update loop.
+
+#### Pre- or Post-update timeouts
+
+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
+label `com.centurylinklabs.watchtower.lifecycle.pre-update-timeout` or post-update-timeout respectively followed by
+the timeout expressed in minutes.
+
+If the label value is explicitly set to `0`, the timeout will be disabled.
### Execution failure
The failure of a command to execute, identified by an exit code different than
-0, 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
log statement containing the exit code will be reported.
diff --git a/docs/linked-containers.md b/docs/linked-containers.md
index 6960b5b..c7e9be8 100644
--- a/docs/linked-containers.md
+++ b/docs/linked-containers.md
@@ -1,3 +1,7 @@
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.
\ No newline at end of file
+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.
+
+If you want to override existing links, or if you are not using links, you can use special `com.centurylinklabs.watchtower.depends-on` label with dependent container names, separated by a comma.
+
+When you have a depending container that is using `network_mode: service:container` then watchtower will treat that container as an implicit link.
diff --git a/docs/metrics.md b/docs/metrics.md
new file mode 100644
index 0000000..480d7c6
--- /dev/null
+++ b/docs/metrics.md
@@ -0,0 +1,42 @@
+!!! warning "Experimental feature"
+ 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.
+
+Metrics can be used to track how Watchtower behaves over time.
+
+To use this feature, you have to set an [API token](arguments.md#http_api_token) and [enable the metrics API](arguments.md#http_api_metrics),
+as well as creating a port mapping for your container for port `8080`.
+
+The metrics API endpoint is `/v1/metrics`.
+
+## Available Metrics
+
+| Name | Type | Description |
+| ------------------------------- | ------- | --------------------------------------------------------------------------- |
+| `watchtower_containers_scanned` | Gauge | Number of containers scanned for changes by watchtower during the last scan |
+| `watchtower_containers_updated` | Gauge | Number of containers updated by watchtower during the last scan |
+| `watchtower_containers_failed` | Gauge | Number of containers where update failed during the last scan |
+| `watchtower_scans_total` | Counter | Number of scans since the watchtower started |
+| `watchtower_scans_skipped` | Counter | Number of skipped scans since watchtower started |
+
+## Example Prometheus `scrape_config`
+
+```yaml
+scrape_configs:
+ - job_name: watchtower
+ scrape_interval: 5s
+ metrics_path: /v1/metrics
+ bearer_token: demotoken
+ static_configs:
+ - targets:
+ - 'watchtower:8080'
+```
+
+Replace `demotoken` with the Bearer token you have set accordingly.
+
+## Demo
+
+The repository contains a demo with prometheus and grafana, available through `docker-compose.yml`. This demo
+is preconfigured with a dashboard, which will look something like this:
+
+
diff --git a/docs/notifications.md b/docs/notifications.md
index b95e95e..d5da4fe 100644
--- a/docs/notifications.md
+++ b/docs/notifications.md
@@ -1,39 +1,262 @@
-
# Notifications
-Watchtower can send notifications when containers are updated. Notifications are sent via hooks in the logging 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:
+Watchtower can send notifications when containers are updated. Notifications are sent via hooks in the logging
+system, [logrus](http://github.com/sirupsen/logrus).
-- `email` to send notifications via e-mail
-- `slack` to send notifications through a Slack webhook
-- `msteams` to send notifications via MSTeams webhook
-- `gotify` to send notifications via Gotify
-
-> 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"`
-
-> 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.
+!!! 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
+ 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:
+ ```
+ 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
-- `--notifications-level` (env. `WATCHTOWER_NOTIFICATIONS_LEVEL`): Controls the log level which is used for the notifications. If omitted, the default log level is `info`. Possible values are: `panic`, `fatal`, `error`, `warn`, `info` or `debug`.
+- `--notifications-level` (env. `WATCHTOWER_NOTIFICATIONS_LEVEL`): Controls the log level which is used for the notifications. If omitted, the default log level is `info`. Possible values are: `panic`, `fatal`, `error`, `warn`, `info`, `debug` or `trace`.
+- `--notifications-hostname` (env. `WATCHTOWER_NOTIFICATIONS_HOSTNAME`): Custom hostname specified in subject/title. Useful to override the operating system hostname.
+- `--notifications-delay` (env. `WATCHTOWER_NOTIFICATIONS_DELAY`): Delay before sending notifications expressed in seconds.
+- Watchtower will post a notification every time it is started. This behavior [can be changed](https://containrrr.github.io/watchtower/arguments/#without_sending_a_startup_message) with an argument.
+- `--notification-title-tag` (env. `WATCHTOWER_NOTIFICATION_TITLE_TAG`): Prefix to include in the title. Useful when running multiple watchtowers.
+- `--notification-skip-title` (env. `WATCHTOWER_NOTIFICATION_SKIP_TITLE`): Do not pass the title param to notifications. This will not pass a dynamic title override to notification services. If no title is configured for the service, it will remove the title all together.
+- `--notification-log-stdout` (env. `WATCHTOWER_NOTIFICATION_LOG_STDOUT`): Enable output from `logger://` shoutrrr service to stdout.
-## Available services
+## [Shoutrrr](https://github.com/containrrr/shoutrrr) notifications
+
+To send notifications via shoutrrr, the following command-line options, or their corresponding environment variables, can be set:
+
+- `--notification-url` (env. `WATCHTOWER_NOTIFICATION_URL`): The shoutrrr service URL to be used. This option can also reference a file, in which case the contents of the file are used.
+
+
+Go to [containrrr.dev/shoutrrr/v0.8/services/overview](https://containrrr.dev/shoutrrr/v0.8/services/overview) to
+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.
+
+- `--notification-template` (env. `WATCHTOWER_NOTIFICATION_TEMPLATE`): The template used for the message.
+
+The template is a Go [template](https://golang.org/pkg/text/template/) that either format a list
+of [log entries](https://pkg.go.dev/github.com/sirupsen/logrus?tab=doc#Entry) or a `notification.Data` struct.
+
+Simple templates are used unless the `notification-report` flag is specified:
+
+- `--notification-report` (env. `WATCHTOWER_NOTIFICATION_REPORT`): Use the session report as the notification template data.
+
+## Simple templates
+
+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 "Skipping notifications"
+ To skip sending notifications that do not contain any information, you can wrap your template with `{{if .}}` and `{{end}}`.
+
+
+Example:
+
+```bash
+docker run -d \
+ --name watchtower \
+ -v /var/run/docker.sock:/var/run/docker.sock \
+ -e WATCHTOWER_NOTIFICATION_URL="discord://token@channel slack://watchtower@token-a/token-b/token-c" \
+ -e WATCHTOWER_NOTIFICATION_TEMPLATE="{{range .}}{{.Time.Format \"2006-01-02 15:04:05\"}} ({{.Level}}): {{.Message}}{{println}}{{end}}" \
+ containrrr/watchtower
+```
+
+## Report templates
+
+The default template for report notifications are the following:
+```go
+{{- if .Report -}}
+ {{- with .Report -}}
+ {{- if ( or .Updated .Failed ) -}}
+{{len .Scanned}} Scanned, {{len .Updated}} Updated, {{len .Failed}} Failed
+ {{- range .Updated}}
+- {{.Name}} ({{.ImageName}}): {{.CurrentImageID.ShortID}} updated to {{.LatestImageID.ShortID}}
+ {{- end -}}
+ {{- range .Fresh}}
+- {{.Name}} ({{.ImageName}}): {{.State}}
+ {{- end -}}
+ {{- range .Skipped}}
+- {{.Name}} ({{.ImageName}}): {{.State}}: {{.Error}}
+ {{- end -}}
+ {{- range .Failed}}
+- {{.Name}} ({{.ImageName}}): {{.State}}: {{.Error}}
+ {{- end -}}
+ {{- end -}}
+ {{- end -}}
+{{- else -}}
+ {{range .Entries -}}{{.Message}}{{"\n"}}{{- end -}}
+{{- end -}}
+```
+
+It will be used to send a summary of every session if there are any containers that were updated or which failed to update.
+
+!!! note "Skipping notifications"
+ Whenever the result of applying the template results in an empty string, no notifications will
+ be sent. This is by default used to limit the notifications to only be sent when there something noteworthy occurred.
+
+ You can replace `{{- if ( or .Updated .Failed ) -}}` with any logic you want to decide when to send the notifications.
+
+Example using a custom report template that always sends a session report after each run:
+
+=== "docker run"
+
+ ```bash
+ docker run -d \
+ --name watchtower \
+ -v /var/run/docker.sock:/var/run/docker.sock \
+ -e WATCHTOWER_NOTIFICATION_REPORT="true" \
+ -e WATCHTOWER_NOTIFICATION_URL="discord://token@channel slack://watchtower@token-a/token-b/token-c" \
+ -e WATCHTOWER_NOTIFICATION_TEMPLATE="
+ {{- if .Report -}}
+ {{- with .Report -}}
+ {{len .Scanned}} Scanned, {{len .Updated}} Updated, {{len .Failed}} Failed
+ {{- range .Updated}}
+ - {{.Name}} ({{.ImageName}}): {{.CurrentImageID.ShortID}} updated to {{.LatestImageID.ShortID}}
+ {{- end -}}
+ {{- range .Fresh}}
+ - {{.Name}} ({{.ImageName}}): {{.State}}
+ {{- end -}}
+ {{- range .Skipped}}
+ - {{.Name}} ({{.ImageName}}): {{.State}}: {{.Error}}
+ {{- end -}}
+ {{- range .Failed}}
+ - {{.Name}} ({{.ImageName}}): {{.State}}: {{.Error}}
+ {{- end -}}
+ {{- end -}}
+ {{- else -}}
+ {{range .Entries -}}{{.Message}}{{\"\n\"}}{{- end -}}
+ {{- end -}}
+ " \
+ containrrr/watchtower
+ ```
+
+=== "docker-compose"
+
+ ``` yaml
+ version: "3"
+ services:
+ watchtower:
+ image: containrrr/watchtower
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
+ env:
+ WATCHTOWER_NOTIFICATION_REPORT: "true"
+ WATCHTOWER_NOTIFICATION_URL: >
+ discord://token@channel
+ slack://watchtower@token-a/token-b/token-c
+ WATCHTOWER_NOTIFICATION_TEMPLATE: |
+ {{- if .Report -}}
+ {{- with .Report -}}
+ {{len .Scanned}} Scanned, {{len .Updated}} Updated, {{len .Failed}} Failed
+ {{- range .Updated}}
+ - {{.Name}} ({{.ImageName}}): {{.CurrentImageID.ShortID}} updated to {{.LatestImageID.ShortID}}
+ {{- end -}}
+ {{- range .Fresh}}
+ - {{.Name}} ({{.ImageName}}): {{.State}}
+ {{- end -}}
+ {{- range .Skipped}}
+ - {{.Name}} ({{.ImageName}}): {{.State}}: {{.Error}}
+ {{- end -}}
+ {{- range .Failed}}
+ - {{.Name}} ({{.ImageName}}): {{.State}}: {{.Error}}
+ {{- end -}}
+ {{- end -}}
+ {{- else -}}
+ {{range .Entries -}}{{.Message}}{{"\n"}}{{- end -}}
+ {{- end -}}
+ ```
+
+## Legacy notifications
+
+For backwards compatibility, the notifications can also be configured using legacy notification options. These will automatically be converted to shoutrrr URLs when used.
+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
+- `slack` to send notifications through a Slack webhook
+- `msteams` to send notifications via MSTeams webhook
+- `gotify` to send notifications via Gotify
+
+### `notify-upgrade`
+If watchtower is started with `notify-upgrade` as it's first argument, it will generate a .env file with your current legacy notification options converted to shoutrrr URLs.
+
+=== "docker run"
+
+ ```bash
+ $ docker run -d \
+ --name watchtower \
+ -v /var/run/docker.sock:/var/run/docker.sock \
+ -e WATCHTOWER_NOTIFICATIONS=slack \
+ -e WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL="https://hooks.slack.com/services/xxx/yyyyyyyyyyyyyyy" \
+ containrrr/watchtower \
+ notify-upgrade
+ ```
+
+=== "docker-compose.yml"
+
+ ```yaml
+ version: "3"
+ services:
+ watchtower:
+ image: containrrr/watchtower
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
+ env:
+ WATCHTOWER_NOTIFICATIONS: slack
+ WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL: https://hooks.slack.com/services/xxx/yyyyyyyyyyyyyyy
+ command: notify-upgrade
+ ```
+
+
+You can then copy this file from the container (a message with the full command to do so will be logged) and use it with your current setup:
+
+=== "docker run"
+
+ ```bash
+ $ docker run -d \
+ --name watchtower \
+ -v /var/run/docker.sock:/var/run/docker.sock \
+ --env-file watchtower-notifications.env \
+ containrrr/watchtower
+ ```
+
+=== "docker-compose.yml"
+
+ ```yaml
+ version: "3"
+ services:
+ watchtower:
+ image: containrrr/watchtower
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
+ env_file:
+ - watchtower-notifications.env
+ ```
### Email
To receive notifications by email, the following command-line options, or their corresponding environment variables, can be set:
-- `--notification-email-from` (env. `WATCHTOWER_NOTIFICATION_EMAIL_FROM`): The e-mail address from which notifications will be sent.
-- `--notification-email-to` (env. `WATCHTOWER_NOTIFICATION_EMAIL_TO`): The e-mail address to which notifications will be sent.
-- `--notification-email-server` (env. `WATCHTOWER_NOTIFICATION_EMAIL_SERVER`): The SMTP server to send e-mails through.
-- `--notification-email-server-tls-skip-verify` (env. `WATCHTOWER_NOTIFICATION_EMAIL_SERVER_TLS_SKIP_VERIFY`): Do not verify the TLS certificate of the mail server. This should be used only for testing.
-- `--notification-email-server-port` (env. `WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT`): The port used to connect to the SMTP server to send e-mails through. Defaults to `25`.
-- `--notification-email-server-user` (env. `WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER`): The username to authenticate with the SMTP server with.
-- `--notification-email-server-password` (env. `WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD`): The password to authenticate with the SMTP server with.
-- `--notification-email-delay` (env. `WATCHTOWER_NOTIFICATION_EMAIL_DELAY`): Delay before sending notifications expressed in seconds.
-- `--notification-email-subjecttag` (env. `WATCHTOWER_NOTIFICATION_EMAIL_SUBJECTTAG`): Prefix to include in the subject tag. Useful when running multiple watchtowers.
+- `--notification-email-from` (env. `WATCHTOWER_NOTIFICATION_EMAIL_FROM`): The e-mail address from which notifications will be sent.
+- `--notification-email-to` (env. `WATCHTOWER_NOTIFICATION_EMAIL_TO`): The e-mail address to which notifications will be sent.
+- `--notification-email-server` (env. `WATCHTOWER_NOTIFICATION_EMAIL_SERVER`): The SMTP server to send e-mails through.
+- `--notification-email-server-tls-skip-verify` (env. `WATCHTOWER_NOTIFICATION_EMAIL_SERVER_TLS_SKIP_VERIFY`): Do not verify the TLS certificate of the mail server. This should be used only for testing.
+- `--notification-email-server-port` (env. `WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT`): The port used to connect to the SMTP server to send e-mails through. Defaults to `25`.
+- `--notification-email-server-user` (env. `WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER`): The username to authenticate with the SMTP server with.
+- `--notification-email-server-password` (env. `WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD`): The password to authenticate with the SMTP server with. Can also reference a file, in which case the contents of the file are used.
+- `--notification-email-delay` (env. `WATCHTOWER_NOTIFICATION_EMAIL_DELAY`): Delay before sending notifications expressed in seconds.
+- `--notification-email-subjecttag` (env. `WATCHTOWER_NOTIFICATION_EMAIL_SUBJECTTAG`): Prefix to include in the subject tag. Useful when running multiple watchtowers. **NOTE:** This will affect all notification types.
Example:
@@ -45,26 +268,74 @@ docker run -d \
-e WATCHTOWER_NOTIFICATION_EMAIL_FROM=fromaddress@gmail.com \
-e WATCHTOWER_NOTIFICATION_EMAIL_TO=toaddress@gmail.com \
-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.gmail.com \
+ -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587 \
-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER=fromaddress@gmail.com \
-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=app_password \
-e WATCHTOWER_NOTIFICATION_EMAIL_DELAY=2 \
containrrr/watchtower
```
+The previous example assumes, that you already have an SMTP server up and running you can connect to. If you don't or you want to bring up watchtower with your own simple SMTP relay the following `docker-compose.yml` might be a good start for you.
+
+The following example assumes, that your domain is called `your-domain.com` and that you are going to use a certificate valid for `smtp.your-domain.com`. This hostname has to be used as `WATCHTOWER_NOTIFICATION_EMAIL_SERVER` otherwise the TLS connection is going to fail with `Failed to send notification email` or `connect: connection refused`. We also have to add a network for this setup in order to add an alias to it. If you also want to enable DKIM or other features on the SMTP server, you will find more information at [freinet/postfix-relay](https://hub.docker.com/r/freinet/postfix-relay).
+
+Example including an SMTP relay:
+
+```yaml
+version: '3.8'
+services:
+ watchtower:
+ image: containrrr/watchtower:latest
+ container_name: watchtower
+ environment:
+ WATCHTOWER_MONITOR_ONLY: 'true'
+ WATCHTOWER_NOTIFICATIONS: email
+ WATCHTOWER_NOTIFICATION_EMAIL_FROM: from-address@your-domain.com
+ WATCHTOWER_NOTIFICATION_EMAIL_TO: to-address@your-domain.com
+ # you have to use a network alias here, if you use your own certificate
+ WATCHTOWER_NOTIFICATION_EMAIL_SERVER: smtp.your-domain.com
+ WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT: 25
+ WATCHTOWER_NOTIFICATION_EMAIL_DELAY: 2
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
+ networks:
+ - watchtower
+ depends_on:
+ - postfix
+
+ # SMTP needed to send out status emails
+ postfix:
+ image: freinet/postfix-relay:latest
+ expose:
+ - 25
+ environment:
+ MAILNAME: somename.your-domain.com
+ TLS_KEY: '/etc/ssl/domains/your-domain.com/your-domain.com.key'
+ TLS_CRT: '/etc/ssl/domains/your-domain.com/your-domain.com.crt'
+ TLS_CA: '/etc/ssl/domains/your-domain.com/intermediate.crt'
+ volumes:
+ - /etc/ssl/domains/your-domain.com/:/etc/ssl/domains/your-domain.com/:ro
+ networks:
+ watchtower:
+ # this alias is really important to make your certificate work
+ aliases:
+ - smtp.your-domain.com
+networks:
+ watchtower:
+ external: false
+```
+
### Slack
-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. If a new version of the _containrrr/watchtower_ image is pushed to the Docker Hub, your watchtower will pull down the new image and restart itself automatically.
To receive notifications in Slack, add `slack` to the `--notifications` option or the `WATCHTOWER_NOTIFICATIONS` environment variable.
-Additionally, you should set the Slack webhook URL using the `--notification-slack-hook-url` option or the `WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL` environment variable.
+Additionally, you should set the Slack webhook URL using the `--notification-slack-hook-url` option or the `WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL` environment variable. This option can also reference a file, in which case the contents of the file are used.
By default, watchtower will send messages under the name `watchtower`, you can customize this string through the `--notification-slack-identifier` option or the `WATCHTOWER_NOTIFICATION_SLACK_IDENTIFIER` environment variable.
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-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.
+- `--notification-slack-channel` (env. `WATCHTOWER_NOTIFICATION_SLACK_CHANNEL`): A string which overrides the webhook's default channel. Example: #my-custom-channel.
Example:
@@ -76,8 +347,6 @@ docker run -d \
-e WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL="https://hooks.slack.com/services/xxx/yyyyyyyyyyyyyyy" \
-e WATCHTOWER_NOTIFICATION_SLACK_IDENTIFIER=watchtower-server-1 \
-e WATCHTOWER_NOTIFICATION_SLACK_CHANNEL=#my-custom-channel \
- -e WATCHTOWER_NOTIFICATION_SLACK_ICON_EMOJI=:whale: \
- -e WATCHTOWER_NOTIFICATION_SLACK_ICON_URL=
