Watchtower

Watchtower uses Go templates to format notification messages. The template engine provides access to two primary data structures: .Report and .Entries.

.Report Object

Used to summarize the status of container updates. It contains several collections that can be iterated over:

• .Scanned: Containers that were checked.
• .Updated: Containers that were successfully updated.
• .Failed: Containers that failed to update.
• .Skipped: Containers that were bypassed.
• .Fresh: Containers that were already up to date.
• .Stale: Containers that require an update.

Each item in these collections typically provides access to:

• .Name: The container name.
• .ImageName: The name of the image.
• .State: The current state of the container.
• .Error: Error messages if applicable.
• .CurrentImageID.ShortID and .LatestImageID.ShortID: Shortened image identifiers for comparison.

.Entries Object

Used to include log entries in the notification. Each entry in the .Entries slice contains:

• .Time: The timestamp of the log (can be formatted using Go's time formatting, e.g., .Time.Format "2006-01-02T15:04:05Z07:00").
• .Level: The log level (e.g., error, warning, info, debug).
• .Message: The actual log message text.

Watchtower supports two modes of notification messaging based on the template data provided:

Simple Templates

By default, Watchtower uses Simple templates. These format a list of logrus log entries. The default template is {{range .}}{{.Message}}{{println}}{{end}}.

To avoid sending empty notifications, wrap your template with {{if .}}{{.}}{{end}}.

Report Templates

If you specify the --notification-report (env WATCHTOWER_NOTIFICATION_REPORT) flag, Watchtower switches to Report templates. These use a notification.Data struct to provide a summary of the entire session (e.g., how many containers were scanned, updated, failed, or skipped).

Default Report Template Structure:

{{- 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 -}}

Watchtower can access private registries by using a config.json file containing credentials. You can either create this file manually or share an existing Docker configuration file generated via docker login.

Manual Configuration

Create a config.json file with the following structure. The auth value must be a base64 encoded string of username:password.

{
    "auths": {
        "<REGISTRY_NAME>": {
            "auth": "XXXXXXX"
        }
    }
}

Registry Name Rules:

• Docker Hub: Use https://index.docker.io/v1/. Watchtower will use these credentials for any image without a specified registry domain.
• Local Registries: Ensure the host matches exactly in both config.json and your container definitions (e.g., localhost, 127.0.0.1, or host.domain:port).
• GCloud: Use _json_key as the username and the content of your gcloudauth.json as the password.

Using an existing Docker config

If you have already run docker login, you can mount your existing ~/.docker/config.json directly into Watchtower.

Mounting the config file

Pass the configuration file to the Watchtower container using a volume mount. By default, Watchtower looks for the file at /config.json inside the container.

Docker CLI:

docker run [...] -v <PATH>/config.json:/config.json containrrr/watchtower

Docker Compose:

version: "3.4"
services:
  watchtower:
    image: containrrr/watchtower:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - <PATH_TO_HOME_DIR>/.docker/config.json:/config.json

# Generate base64 auth string
echo -n 'username:password' | base64

# For GCloud
echo -n "_json_key:$(cat gcloudauth.json)" | base64 -w0

Lifecycle hooks allow you to execute shell commands inside a container before or after an update. This feature is disabled by default. To enable it, use one of the following methods:

• CLI Flag: Add --enable-lifecycle-hooks to your Watchtower command.
• Environment Variable: Set WATCHTOWER_LIFECYCLE_HOOKS to true.

Important Requirements & Constraints:

• Shell Availability: Commands are executed using sh, so the target container must include the sh executable.
• Container State: If a container is not currently running, lifecycle hooks will not execute, and the update will proceed without them.
• Failure Behavior: If a command fails (returns an exit code other than 0 or 75), Watchtower will log the error but will not stop the update process.

# Using environment variable
WATCHTOWER_LIFECYCLE_HOOKS=true watchtower

# Using CLI flag
watchtower --enable-lifecycle-hooks

Watchtower uses the Shoutrrr library to send notifications. You can specify one or multiple notification services by providing a space-separated list of Shoutrrr service URLs.

Key Configuration Options

• --notification-url (env WATCHTOWER_NOTIFICATION_URL): The Shoutrrr service URL(s). This can also be a path to a file containing the URL(s).
• --notification-template (env WATCHTOWER_NOTIFICATION_TEMPLATE): A Go text/template used to format the message.
• --notification-report (env WATCHTOWER_NOTIFICATION_REPORT): When enabled, Watchtower uses the session report data instead of individual log entries for the template.

Important: Multiple Notifications Workaround

Due to a bug in Viper, you cannot use comma-separated values in environment variables for multiple notifications. Instead, use spaces to separate URLs and wrap the value in quotes:

WATCHTOWER_NOTIFICATION_URL="slack://token1 slack://token2"

Note: If using docker-compose, do not use double quotes inside your .yml file for these values to avoid startup errors.

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