From 9587034959609bd4351068755546417a2585e0d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?nils=20m=C3=A5s=C3=A9n?= Date: Mon, 19 Sep 2022 14:14:58 +0200 Subject: [PATCH] add docs for new templates --- docs/notifications.md | 172 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 169 insertions(+), 3 deletions(-) diff --git a/docs/notifications.md b/docs/notifications.md index e82f6fb..9894954 100644 --- a/docs/notifications.md +++ b/docs/notifications.md @@ -38,8 +38,14 @@ 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/) and that 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/) 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. @@ -56,12 +62,116 @@ Example: docker run -d \ --name watchtower \ -v /var/run/docker.sock:/var/run/docker.sock \ - -e WATCHTOWER_NOTIFICATIONS=shoutrrr \ -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: +``` +{{- 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. @@ -73,6 +183,62 @@ The types of notifications to send are set by passing a comma-separated list of - `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: