Watchtower

https://watchtower.nickfedor.com/v1.14.2
Admin
Watchtower is an application that automates Docker container image updates by monitoring running...
Tokens:67,088
Snippets:625
Trust Score:5.7
Update:7 months ago
Show doc for...
Tokens:
Raw
### Download Docker Compose file for Watchtower (PowerShell)

Source: https://watchtower.nickfedor.com/v1.14.2/quickstart

This PowerShell command downloads the example Docker Compose file for Watchtower from its GitHub repository. The file defines the Watchtower service configuration.

```powershell
iwr -Uri https://raw.githubusercontent.com/nicholas-fedor/watchtower/refs/heads/main/examples/default/docker-compose.yaml -OutFile docker-compose.yaml
```

--------------------------------

### Download Docker Compose file for Watchtower (Bash)

Source: https://watchtower.nickfedor.com/v1.14.2/quickstart

This Bash command downloads the example Docker Compose file for Watchtower using curl. The downloaded file can then be used to deploy Watchtower with Docker Compose.

```bash
curl -L https://raw.githubusercontent.com/nicholas-fedor/watchtower/refs/heads/main/examples/default/docker-compose.yaml -o docker-compose.yaml
```

--------------------------------

### Signal Notification Setup Examples (Docker)

Source: https://watchtower.nickfedor.com/v1.14.2/notifications/overview

Provides examples of how to configure Watchtower to send Signal notifications using Docker. This includes configurations using environment variables, command-line flags, and Docker Compose.

```docker
docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_NOTIFICATION_URL=signal://localhost:8080/+1234567890/+0987654321 \
  nickfedor/watchtower
```

```docker
docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower \
  --notification-url "signal://localhost:8080/+1234567890/+0987654321"
```

```yaml
services:
  watchtower:
    image: nickfedor/watchtower:latest
    environment:
      WATCHTOWER_NOTIFICATION_URL: signal://localhost:8080/+1234567890/+0987654321
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
```

--------------------------------

### Watchtower Docker Compose Configuration

Source: https://watchtower.nickfedor.com/v1.14.2/quickstart

This is an example Docker Compose file that configures the Watchtower service. It specifies the image to use, restart policy, and volume mounts necessary for Watchtower to function.

```yaml
services:
  watchtower:
    image: nickfedor/watchtower:latest
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
```

--------------------------------

### Download and Extract Watchtower Binary - PowerShell

Source: https://watchtower.nickfedor.com/v1.14.2/getting-started/installation_q=

This PowerShell script downloads the Watchtower binary for Windows (amd64) from GitHub Releases, extracts it, and places it in the current directory. It uses the GitHub API to find the latest release and download the correct zip file. The script checks for successful installation and provides feedback.

```powershell
iwr (iwr https://api.github.com/repos/nicholas-fedor/watchtower/releases/latest | ConvertFrom-Json).assets.where({$_.name -like "*windows_amd64*.zip"}).browser_download_url -OutFile watchtower.zip; Add-Type -AssemblyName System.IO.Compression.FileSystem; $zip = [System.IO.Compression.ZipFile]::OpenRead("$PWD\watchtower.zip"); $zip.Entries | Where-Object {$_.Name -eq 'watchtower.exe'} | ForEach-Object {[System.IO.Compression.ZipFileExtensions]::ExtractToFile($_, "$PWD\watchtower.exe", $true)}; $zip.Dispose(); Remove-Item watchtower.zip; if (Test-Path ".\watchtower.exe") { Write-Host "Successfully installed watchtower.exe to current directory" } else { Write-Host "Failed to install watchtower.exe" }
```

--------------------------------

### Run Watchtower using Docker Compose

Source: https://watchtower.nickfedor.com/v1.14.2/quickstart

This command deploys the Watchtower service defined in the 'docker-compose.yaml' file. It starts the container in detached mode, allowing it to run in the background.

```bash
docker compose up -d
```

--------------------------------

### Download and Extract Watchtower Binary - Bash

Source: https://watchtower.nickfedor.com/v1.14.2/getting-started/installation_q=

This Bash script downloads the Watchtower binary for Linux (amd64) and macOS (amd64) from GitHub Releases, extracts it, and places it in the current directory. It uses `curl` to fetch the download URL from the GitHub API and `tar` to extract the archive. The script checks for successful installation and provides feedback.

```bash
curl -L $(curl -s https://api.github.com/repos/nicholas-fedor/watchtower/releases/latest | grep -o 'https://[^"*linux_amd64[^"*\.tar\.gz') | tar -xz -C . watchtower && if [ -f ./watchtower ]; then echo "Successfully installed watchtower to current directory"; else echo "Failed to install watchtower"; fi
```

```bash
curl -L $(curl -s https://api.github.com/repos/nicholas-fedor/watchtower/releases/latest | grep -o 'https://[^"*darwin_amd64[^"*\.tar\.gz') | tar -xz -C . watchtower && if [ -f ./watchtower ]; then echo "Successfully installed watchtower to current directory"; else echo "Failed to install watchtower"; fi
```

--------------------------------

### Watchtower HTTP API Configuration Examples (CLI)

Source: https://watchtower.nickfedor.com/v1.14.2/advanced-features/http-api_q=

Examples demonstrating how to configure the Watchtower HTTP API's listening address and port using command-line arguments. This allows customization of where the API server binds and listens for requests.

```bash
--http-api-port=8080
```

```bash
--http-api-host=127.0.0.1 --http-api-port=8080
```

```bash
--http-api-host=192.168.1.100 --http-api-port=9090
```

--------------------------------

### Configure Docker Daemon for TLS (Example)

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/secure-connections

Illustrates how to start the Docker daemon with TLS verification enabled, specifying the paths to the CA certificate, server certificate, and server private key.

```bash
dockerd --tlsverify --tlscacert=/path/to/ca.pem --tlscert=/path/to/server-cert.pem --tlskey=/path/to/server-key.pem -H=tcp://0.0.0.0:2376
```

--------------------------------

### WordPress and MySQL Dependency Example

Source: https://watchtower.nickfedor.com/v1.14.2/advanced-features/linked-containers

Demonstrates a common WordPress and MySQL setup using Docker Compose. Watchtower correctly identifies the dependency, ensuring MySQL is updated before WordPress to maintain database connectivity.

```yaml
services:
  wordpress:
    image: wordpress:latest
    depends_on:
      - mysql
    environment:
      WORDPRESS_DB_HOST: mysql
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: example

```

--------------------------------

### Watchtower Docker Compose Configuration

Source: https://watchtower.nickfedor.com/v1.14.2/quickstart_q=

This is the content of the `docker-compose.yaml` file for Watchtower. It specifies the Watchtower image to use, the restart policy, and mounts the Docker socket, enabling it to monitor and manage other containers.

```yaml
services:
  watchtower:
    image: nickfedor/watchtower:latest
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

```

--------------------------------

### Docker Usage Example with Split Notifications

Source: https://watchtower.nickfedor.com/v1.14.2/notifications/overview

An example of how to run Watchtower in Docker, enabling separate notifications for each container update using the `WATCHTOWER_NOTIFICATION_SPLIT_BY_CONTAINER` environment variable.

```dockerfile
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" \
  -e WATCHTOWER_NOTIFICATION_SPLIT_BY_CONTAINER=true \
  nickfedor/watchtower
```

--------------------------------

### Example: Run Watchtower with Auto CPU Copy Mode

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/arguments

Demonstrates running Watchtower with the `--cpu-copy-mode auto` argument, which automatically detects the environment (Docker or Podman) and adjusts CPU settings for compatibility.

```dockerfile
docker run -d \
    --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    nickfedor/watchtower \
    --cpu-copy-mode auto
```

--------------------------------

### Example: Run Watchtower with Full CPU Copy Mode

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/arguments

Shows how to run Watchtower with `--cpu-copy-mode full`, forcing all CPU settings to be copied unchanged. This is suitable for Docker-only environments where preserving all CPU limits is desired.

```dockerfile
docker run -d \
    --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    nickfedor/watchtower \
    --cpu-copy-mode full
```

--------------------------------

### Watchtower Docker CLI Example with TLS

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/secure-connections

This example demonstrates how to run the Watchtower container using the Docker CLI with TLS verification enabled. It maps certificate volumes and specifies the Docker host and certificate path.

```docker
docker run -d \
  --name watchtower \
  -v /path/to/certs:/etc/ssl/docker:ro \
  nickfedor/watchtower --host tcp://remote-host:2376 --cert-path /etc/ssl/docker --tlsverify

```

--------------------------------

### Docker Commands for Credential Helper Setup

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/private-registries_q=

These Docker commands are used to create a volume for the credential helper, build the helper image, and run it to store the compiled binary in the created volume.

```bash
docker volume create helper

docker build -t aws-ecr-dock-cred-helper .

docker run  -d --rm --name aws-cred-helper \
  --volume helper:/go/bin aws-ecr-dock-cred-helper

```

--------------------------------

### Docker Compose Example with Custom Notification Template

Source: https://watchtower.nickfedor.com/v1.14.2/notifications/templates

Example of configuring Watchtower using Docker Compose, enabling report notifications and specifying a custom notification template. The template is defined within the `docker-compose.yml` file.

```yaml
services:
  watchtower:
    image: watchtower-image
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      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 .Restarted}} Restarted, {{len .Failed}} Failed
        {{- if ( or .Updated .Restarted .Failed ) -}}
            {{- range .Updated -}}
        - {{.Name}} ({{.ImageName}}): {{.CurrentImageID.ShortID}} updated to {{.LatestImageID.ShortID}}
            {{- end -}}
            {{- range .Fresh -}}
        - {{.Name}} ({{.ImageName}}): {{.State}}
            {{- end -}}
            {{- range .Restarted -}}
        - {{.Name}} ({{.ImageName}}): {{.State}}
            {{- end -}}
            {{- range .Skipped -}}
        - {{.Name}} ({{.ImageName}}): {{.State}}: {{.Error}}
            {{- end -}}
            {{- range .Failed -}}
        - {{.Name}} ({{.ImageName}}): {{.State}}: {{.Error}}
            {{- end -}}
        {{- end -}}
          {{- end -}}
        {{- if .Entries -}}

        Logs:
        {{- end -}}
        {{- range .Entries -}}{{.Time.Format "2006-01-02T15:04:05Z07:00"}} [{{.Level}}] {{.Message}}{{"\n"}}{{- end -}}
        {{- end -}}
```

--------------------------------

### Docker CLI Example with Custom Notification Template

Source: https://watchtower.nickfedor.com/v1.14.2/notifications/templates

Example of running Watchtower using the Docker CLI, enabling report notifications and setting a custom notification template via an environment variable. The template is embedded directly in the command.

```bash
docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_NOTIFICATION_REPORT="true" \
  -e WATCHTOWER_NOTIFICATION_TEMPLATE="\
{{- if .Report -}} \
  {{- with .Report -}} \
{{len .Scanned}} Scanned, {{len .Updated}} Updated, {{len .Restarted}} Restarted, {{len .Failed}} Failed \
{{- if ( or .Updated .Restarted .Failed ) -}} \
      {{- range .Updated -}} \
- {{.Name}} ({{.ImageName}}): {{.CurrentImageID.ShortID}} updated to {{.LatestImageID.ShortID}} \
      {{- end -}} \
      {{- range .Fresh -}} \
- {{.Name}} ({{.ImageName}}): {{.State}} \
      {{- end -}} \
      {{- range .Restarted -}} \
- {{.Name}} ({{.ImageName}}): {{.State}} \
      {{- end -}} \
      {{- range .Skipped -}} \
- {{.Name}} ({{.ImageName}}): {{.State}}: {{.Error}} \
      {{- end -}} \
      {{- range .Failed -}} \
- {{.Name}} ({{.ImageName}}): {{.State}}: {{.Error}} \
      {{- end -}} \
{{- end -}} \
  {{- end -}} \
{{- if .Entries -}} \

Logs: \
{{- end -}} \
{{- range .Entries -}}{{.Time.Format \"2006-01-02T15:04:05Z07:00\"}} [{{.Level}}] {{.Message}}{{\"\n\"}}{{- end -}} \
{{- end -}}" \
  watchtower-image
```

--------------------------------

### Watchtower Docker Compose Configuration Example

Source: https://watchtower.nickfedor.com/v1.14.2/advanced-features/http-api_q=

A Docker Compose configuration file demonstrating how to set up Watchtower with its HTTP API enabled for both updates and metrics. It includes volume mounts, environment variables for authentication, and port mappings.

```yaml
services:
  app-monitored-by-watchtower:
    image: myapps/monitored-by-watchtower
    labels:
      - "com.centurylinklabs.watchtower.enable=true"

  watchtower:
    image: nickfedor/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --http-api-update --http-api-metrics
    environment:
      - WATCHTOWER_HTTP_API_TOKEN=mytoken
    labels:
      - "com.centurylinklabs.watchtower.enable=false"
    ports:
      - 8080:8080
    restart: unless-stopped
```

--------------------------------

### Watchtower HTTP API Update Trigger Examples (curl)

Source: https://watchtower.nickfedor.com/v1.14.2/advanced-features/http-api_q=

Examples using `curl` to trigger container updates via the Watchtower HTTP API. These demonstrate how to authenticate requests and optionally filter updates by image name and tag.

```bash
curl -H "Authorization: Bearer mytoken" localhost:8080/v1/update
```

```bash
curl -H "Authorization: Bearer mytoken" localhost:8080/v1/update?image=foo/bar:1.0,foo/baz:latest
```

```bash
curl -H "Authorization: Bearer mytoken" localhost:8080/v1/update?image=foo/bar,foo/baz
```

--------------------------------

### Example: Run Watchtower with No CPU Copy Mode

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/arguments

Illustrates running Watchtower with `--cpu-copy-mode none`, which strips all CPU limits from recreated containers. This is useful for avoiding compatibility issues when CPU limits cause problems.

```dockerfile
docker run -d \
    --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    nickfedor/watchtower \
    --cpu-copy-mode none
```

--------------------------------

### Example Output for Simple Template

Source: https://watchtower.nickfedor.com/v1.14.2/notifications/templates

Illustrates the expected output of a simple template when processing a log entry with `msg="Found new image"`. This shows how container and image details are formatted.

```text
Found new image: repo/image:latest (abcdef123456)
```

--------------------------------

### Watchtower Docker Compose Example with TLS

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/secure-connections

This example shows how to configure Watchtower as a service in a Docker Compose file for secure TLS connections. It utilizes environment variables for Docker host, certificate path, and TLS verification.

```yaml
services:
  watchtower:
    image: nickfedor/watchtower
    environment:
      - DOCKER_HOST=tcp://remote-host:2376
      - DOCKER_CERT_PATH=/etc/ssl/docker
      - DOCKER_TLS_VERIFY=1
    volumes:
      - /path/to/certs:/etc/ssl/docker:ro
    restart: unless-stopped

```

--------------------------------

### Example Notification Output

Source: https://watchtower.nickfedor.com/v1.14.2/notifications/templates

An example of the output generated by the default Watchtower notification report template for a session with one updated container, one restarted container, and one error log entry. This demonstrates the structure of the report.

```text
5 Scanned, 1 Updated, 1 Restarted, 0 Failed
- /container (repo/image:latest): abcdef12 updated to 34567890
- /restarted-container (repo/image:latest): Restarted

Logs:
2025-08-20T06:00:13-07:00 [error] Operation failed. Try again later.
```

--------------------------------

### Run Watchtower with Custom config.json

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/private-registries_q=

This command starts the Watchtower Docker container, mounting a custom `config.json` file into the container at `/config.json`. Replace `<PATH>` with the actual path to your configuration file.

```bash
docker run [...] -v <PATH>/config.json:/config.json nickfedor/watchtower
```

--------------------------------

### Run Watchtower with Docker's config.json

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/private-registries_q=

This command starts the Watchtower Docker container, mounting the user's default Docker configuration file (`~/.docker/config.json`) into the container at `/config.json`. Replace `<PATH_TO_HOME_DIR>` with the path to your home directory.

```bash
docker run [...] -v <PATH_TO_HOME_DIR>/.docker/config.json:/config.json nickfedor/watchtower
```

--------------------------------

### Signal Notification Setup and URL Format

Source: https://watchtower.nickfedor.com/v1.14.2/notifications/overview_q=

Configure and send notifications using Signal via Shoutrrr.

```APIDOC
## Signal Notifications

### Description
Watchtower uses Shoutrrr's Signal service to send Signal notifications. This requires a Signal API server (e.g., signal-cli-rest-api) running and accessible.

### Setting up Signal API Server
1. **Phone Number**: A dedicated phone number registered with Signal.
2. **API Server**: A server running signal-cli with REST API capabilities.
3. **Account Linking**: Link the server as a secondary device to your Signal account.
4. **Optional Security Layer**: Authentication and endpoint restrictions via a proxy.

The server must be able to receive SMS verification codes during initial setup and maintain a persistent connection to Signal's servers.

### Signal URL Format
```
signal://[user:password@]host:port/source_phone/recipient1/recipient2
```

#### Parameters
- **host** (String) - Required - Signal API server hostname or IP address.
- **port** (Integer) - Optional - Signal API server port. Defaults to `8080`.
- **user** (String) - Optional - Username for HTTP Basic Authentication.
- **password** (String) - Optional - Password for HTTP Basic Authentication.
- **source_phone** (String) - Required - Your Signal phone number with country code (e.g., `+1234567890`).
- **recipient1, recipient2** (String) - Required - Phone numbers or group IDs to send to.

#### TLS Configuration
- Use `signal://` for HTTPS (default, recommended).
- Use `signal://...?disabletls=yes` for HTTP (insecure, for local testing only).

#### Examples
**Send to a single phone number:**
```
signal://localhost:8080/+1234567890/+0987654321
```

**Send to multiple recipients:**
```
signal://localhost:8080/+1234567890/+0987654321/+1123456789/group.testgroup
```

**Send to a group:**
```
signal://localhost:8080/+1234567890/group.abcdefghijklmnop=
```

**With authentication:**
```
signal://user:password@localhost:8080/+1234567890/+0987654321
```

**With API token (Bearer auth):**
```
signal://localhost:8080/+1234567890/+0987654321?token=YOUR_API_TOKEN
```

**Using HTTP instead of HTTPS:**
```
signal://localhost:8080/+1234567890/+0987654321?disabletls=yes
```

### Signal Attachments

#### Description
The Signal service supports sending base64-encoded attachments.

#### Request Example
```bash
shoutrrr send "signal://localhost:8080/+1234567890/+0987654321" \
  "Message with attachment" \
  --attachments "base64data1,base64data2"
```

**Note**: Attachments must be provided as base64-encoded data. The API server handles MIME type detection and file handling.
```

--------------------------------

### Enable Update on Startup for Watchtower

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/arguments_q=

Configure Watchtower to perform an update check immediately upon starting using the `--update-on-start` flag. If a schedule is also set, it will proceed with periodic updates.

```bash
docker run -d \
    -v /var/run/docker.sock:/var/run/docker.sock \
    nickfedor/watchtower \
    --update-on-start

```

--------------------------------

### Check Docker Version

Source: https://watchtower.nickfedor.com/v1.14.2/getting-started/usage

This command allows you to verify the version of the Docker engine installed on your host system. Ensuring compatibility with Watchtower is crucial for stable operation.

```bash
docker version

```

--------------------------------

### Conditional Backup Logic Based on Labels in Bash

Source: https://watchtower.nickfedor.com/v1.14.2/advanced-features/lifecycle-hooks

Uses a case statement to perform different backup actions based on the value of the 'com.centurylinklabs.watchtower.backup-type' label. Supports 'full', 'incremental', and a default backup type. Requires the WT_CONTAINER environment variable and jq to be installed.

```bash
#!/bin/bash
BACKUP_TYPE=$(echo $WT_CONTAINER | jq -r '.labels["com.centurylinklabs.watchtower.backup-type"] // "default"')
case $BACKUP_TYPE in
    "full")
        echo "Performing full backup"
        # Full backup logic
        ;;
    "incremental")
        echo "Performing incremental backup"
        # Incremental backup logic
        ;;
    *)
        echo "Performing default backup"
        # Default backup logic
        ;;
esac

```

--------------------------------

### Configure Watchtower to Update on Startup (Docker CLI)

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/arguments

This command starts Watchtower and immediately performs an update check for all monitored containers. If a schedule or interval is also set, Watchtower will continue with periodic updates after the initial startup check.

```docker
docker run -d \
    --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    nickfedor/watchtower \
    --update-on-start

```

--------------------------------

### Execute Pre-Update Backup Script from Labels in Bash, Python, and Go

Source: https://watchtower.nickfedor.com/v1.14.2/advanced-features/lifecycle-hooks

Checks for a 'com.centurylinklabs.watchtower.lifecycle.pre-update' label in the container's metadata and executes the script specified if found. This allows for custom pre-update actions. Requires the WT_CONTAINER environment variable to be set.

```bash
#!/bin/bash
BACKUP_SCRIPT=$(echo $WT_CONTAINER | jq -r '.labels["com.centurylinklabs.watchtower.lifecycle.pre-update"]')
if [ -n "$BACKUP_SCRIPT" ]; then
    echo "Running backup: $BACKUP_SCRIPT"
    $BACKUP_SCRIPT
fi

```

```python
import os
import json

container_info = json.loads(os.environ['WT_CONTAINER'])
backup_script = container_info['labels'].get('com.centurylinklabs.watchtower.lifecycle.pre-update')
if backup_script:
    print(f"Running backup: {backup_script}")
    # Execute backup_script

```

```go
package main

import (
    "encoding/json"
    "fmt"
    "os"
)

func main() {
    var container struct {
        Labels map[string]string `json:"labels"`
    }

    if err := json.Unmarshal([]byte(os.Getenv("WT_CONTAINER")), &container); err != nil {
        panic(err)
    }

    if backupScript, exists := container.Labels["com.centurylinklabs.watchtower.lifecycle.pre-update"]; exists {
        fmt.Printf("Running backup: %s\n", backupScript)
        // Execute backupScript
    }
}

```

--------------------------------

### Pull Watchtower Container Image - Docker

Source: https://watchtower.nickfedor.com/v1.14.2/getting-started/installation_q=

This command pulls the latest Watchtower container image from Docker Hub and GitHub Container Registry.  It allows users to obtain the necessary image for running Watchtower.  Ensure Docker is installed and configured correctly before running this command.

```docker
docker pull nickfedor/watchtower:latest
```

```docker
docker pull ghcr.io/nicholas-fedor/watchtower:latest
```

--------------------------------

### Watchtower Notification Summary Log

Source: https://watchtower.nickfedor.com/v1.14.2/notifications/overview

Example log output from Watchtower indicating the notification services that have been successfully configured and are being used. This is useful for verifying multiple notification setups.

```text
time="2026-01-28T16:07:24+01:00" level=info msg="Using notifications: discord, telegram"

```

--------------------------------

### Dockerfile: Database Backup and Migration Hooks

Source: https://watchtower.nickfedor.com/v1.14.2/advanced-features/lifecycle-hooks

This Dockerfile demonstrates how to configure Watchtower lifecycle hooks for a PostgreSQL container. It specifies a 'pre-update' hook to run a backup script before stopping the old container and a 'post-update' hook to execute migration scripts after the new container starts. It also includes labels for timeout configurations.

```dockerfile
FROM postgres:13

# Pre-update: Create backup before stopping
LABEL com.centurylinklabs.watchtower.lifecycle.pre-update="/usr/local/bin/backup.sh"
LABEL com.centurylinklabs.watchtower.lifecycle.pre-update-timeout="10"

# Post-update: Run migrations after starting new version
LABEL com.centurylinklabs.watchtower.lifecycle.post-update="/usr/local/bin/migrate.sh"
LABEL com.centurylinklabs.watchtower.lifecycle.post-update-timeout="15"

COPY backup.sh migrate.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/backup.sh /usr/local/bin/migrate.sh

```

--------------------------------

### Display Watchtower Help Information

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/arguments_q=

Show the help documentation for Watchtower to list all supported flags and their descriptions. This is useful for understanding available configurations.

```bash
docker run \
    -v /var/run/docker.sock:/var/run/docker.sock \
    nickfedor/watchtower \
    --help

```

--------------------------------

### Run Watchtower using Docker CLI

Source: https://watchtower.nickfedor.com/v1.14.2/quickstart

This command pulls and runs the Watchtower container in detached mode. It mounts the Docker socket to allow Watchtower to interact with the Docker daemon and ensures the container restarts unless explicitly stopped.

```bash
docker run -d \
  --name watchtower \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower
```

--------------------------------

### Wait for Application Readiness with Shell Script

Source: https://watchtower.nickfedor.com/v1.14.2/advanced-features/lifecycle-hooks

This snippet demonstrates how to use a shell script to wait for an application to become ready after an update. It's configured using Docker Compose labels for the post-update hook.

```docker-compose
version: '3.8'
services:
  node-app:
    image: node:18
    working_dir: /app
    volumes:
      - ./app:/app
      - ./wait-for-app.sh:/wait-for-app.sh:ro
    ports:
      - "3000:3000"
    command: npm start
    labels:
      - "com.centurylinklabs.watchtower.lifecycle.pre-update=pkill -TERM node"
      - "com.centurylinklabs.watchtower.lifecycle.pre-update-timeout=2"
      - "com.centurylinklabs.watchtower.lifecycle.post-update=/wait-for-app.sh"
      - "com.centurylinklabs.watchtower.lifecycle.post-update-timeout=5"

  watchtower:
    image: nicholas-fedor/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_LIFECYCLE_HOOKS=true
      - WATCHTOWER_POLL_INTERVAL=30

```

```shell
#!/bin/sh
# /wait-for-app.sh

# Example script to wait for an application
# Add your specific readiness check logic here

echo "Waiting for application to be ready..."
# sleep 10 # Example: wait for 10 seconds
# Add actual health check commands

echo "Application is ready."
exit 0

```

--------------------------------

### Configure HTTP Proxy for Registry Connections

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/arguments

Sets up an HTTP proxy for registry connections by respecting the HTTP_PROXY environment variable. This is useful in environments without direct internet access. Both uppercase and lowercase variants of the environment variable are supported.

```shell
Argument: None
Environment Variable: HTTP_PROXY / http_proxy
                Type: String (e.g., "http://proxy.example.com:3128")
             Default: None
```

--------------------------------

### Example Text JSON Report

Source: https://watchtower.nickfedor.com/v1.14.2/notifications/template-preview

An example of a text-based JSON report generated by Watchtower, summarizing container update statuses. It includes counts for scanned, updated, failed, and restarted containers, along with details for each container's status and image information.

```json
{
  "Entries": [
    {
      "Message": "Failed to find new image",
      "Data": {},
      "Time": "2026-03-02T14:07:28.696Z",
      "Level": "error"
    },
    {
      "Message": "Failed to remove image",
      "Data": {},
      "Time": "2026-03-02T14:07:34.696Z",
      "Level": "warning"
    },
    {
      "Message": "Failed to stop container",
      "Data": {},
      "Time": "2026-03-02T14:07:51.696Z",
      "Level": "warning"
    },
    {
      "Message": "Note that the first check will be performed in 5 hours, 59 minutes, 22 seconds",
      "Data": {},
      "Time": "2026-03-02T14:08:09.696Z",
      "Level": "info"
    },
    {
      "Message": "Watchtower v1.11.7 using Docker API v1.51",
      "Data": {},
      "Time": "2026-03-02T14:08:32.696Z",
      "Level": "info"
    },
    {
      "Message": "Found new image",
      "Data": {},
      "Time": "2026-03-02T14:08:36.696Z",
      "Level": "info"
    },
    {
      "Message": "Scheduling first run: 2025-08-19 06:00:00 +0000 UTC",
      "Data": {},
      "Time": "2026-03-02T14:08:50.696Z",
      "Level": "debug"
    },
    {
      "Message": "Found new image",
      "Data": {},
      "Time": "2026-03-02T14:08:57.696Z",
      "Level": "debug"
    },
    {
      "Message": "Removing image",
      "Data": {},
      "Time": "2026-03-02T14:09:24.696Z",
      "Level": "debug"
    },
    {
      "Message": "Checking all containers (except explicitly disabled with label)",
      "Data": {},
      "Time": "2026-03-02T14:09:42.696Z",
      "Level": "debug"
    }
  ],
  "StaticData": {
    "Title": "Title",
    "Host": "Host"
  }
}
```

--------------------------------

### GET /v1/metrics

Source: https://watchtower.nickfedor.com/v1.14.2/advanced-features/http-api_q=

Exposes Prometheus-compatible metrics for monitoring and alerting. This endpoint does not require authentication.

```APIDOC
## GET /v1/metrics

### Description
Exposes Prometheus-compatible metrics for monitoring and alerting purposes.

### Method
GET

### Endpoint
`/v1/metrics`

### Parameters
This endpoint does not accept any parameters.

### Request Example
```bash
curl localhost:8080/v1/metrics
```

### Response
#### Success Response (200)
Returns Prometheus-formatted metrics. The exact metrics exposed may vary based on Watchtower's runtime status and configuration.

#### Response Example
```text
# HELP watchtower_container_scanned_total Total number of containers scanned for updates
# TYPE watchtower_container_scanned_total counter
watchtower_container_scanned_total 15
# HELP watchtower_container_updated_total Total number of containers successfully updated
# TYPE watchtower_container_updated_total counter
watchtower_container_updated_total 3
# HELP watchtower_container_failed_total Total number of containers that failed to update
# TYPE watchtower_container_failed_total counter
watchtower_container_failed_total 1
# HELP watchtower_last_run_duration_seconds Last run duration in seconds
# TYPE watchtower_last_run_duration_seconds gauge
watchtower_last_run_duration_seconds 120.5
```
```

--------------------------------

### Docker Compose: Database Backup and Migration Hooks

Source: https://watchtower.nickfedor.com/v1.14.2/advanced-features/lifecycle-hooks

This Docker Compose configuration sets up a PostgreSQL service and Watchtower, integrating lifecycle hooks for database management. It uses labels on the PostgreSQL service to define 'pre-update' and 'post-update' hooks, including their respective timeouts, ensuring data integrity during updates. The Watchtower service is configured to enable lifecycle hooks.

```yaml
version: '3.8'
services:
  postgres:
    image: postgres:13
    environment:
      POSTGRES_DB: mydb
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./backup.sh:/usr/local/bin/backup.sh:ro
      - ./migrate.sh:/usr/local/bin/migrate.sh:ro
    labels:
      - "com.centurylinklabs.watchtower.lifecycle.pre-update=/usr/local/bin/backup.sh"
      - "com.centurylinklabs.watchtower.lifecycle.pre-update-timeout=10"
      - "com.centurylinklabs.watchtower.lifecycle.post-update=/usr/local/bin/migrate.sh"
      - "com.centurylinklabs.watchtower.lifecycle.post-update-timeout=15"

  watchtower:
    image: nicholas-fedor/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_LIFECYCLE_HOOKS=true
      - WATCHTOWER_POLL_INTERVAL=30

volumes:
  postgres_data:

```

--------------------------------

### GET /v1/metrics

Source: https://watchtower.nickfedor.com/v1.14.2/advanced-features/metrics

Retrieves Prometheus-compatible metrics about Watchtower's operation. This endpoint is experimental and requires the metrics API to be enabled.

```APIDOC
## GET /v1/metrics

### Description
Retrieves Prometheus-compatible metrics about Watchtower's operation. This endpoint is experimental and requires the metrics API to be enabled.

### Method
GET

### Endpoint
/v1/metrics

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **metrics** (string) - Prometheus-formatted metrics string.

#### Response Example
```
# HELP watchtower_containers_scanned Number of containers scanned for changes by watchtower during the last scan
# TYPE watchtower_containers_scanned gauge
watchtower_containers_scanned 5
# HELP watchtower_containers_updated Number of containers updated by watchtower during the last scan
# TYPE watchtower_containers_updated gauge
watchtower_containers_updated 2
```
```

--------------------------------

### Configure HTTPS Proxy for Registry Connections

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/arguments

Sets up an HTTPS proxy for registry connections by respecting the HTTPS_PROXY environment variable. This is useful in environments without direct internet access. Both uppercase and lowercase variants of the environment variable are supported.

```shell
Argument: None
Environment Variable: HTTPS_PROXY / https_proxy
                Type: String (e.g., "http://proxy.example.com:3128")
             Default: None
```

--------------------------------

### Email Notifications

Source: https://watchtower.nickfedor.com/v1.14.2/notifications/overview

Configure email notifications using Shoutrrr's SMTP service, with examples for Gmail, AWS SES, Microsoft 365, and generic configurations.

```APIDOC
## Email Notifications

### Description
Watchtower uses Shoutrrr's smtp service to send email notifications. Either legacy email notification flags or Shoutrrr URLs can be used; however, directly using URLs is recommended for greater control and clarity, especially for configuring TLS settings (e.g., STARTTLS or Implicit TLS).

To send notifications via e-mail, add `email` to the `--notifications` option or the `WATCHTOWER_NOTIFICATIONS` environment variable.

Email notification flags (e.g., `WATCHTOWER_NOTIFICATION_EMAIL_SERVER`, `WATCHTOWER_NOTIFICATION_EMAIL_FROM`) are automatically converted to a Shoutrrr SMTP URL internally.

### Common SMTP Configurations

#### Gmail
- **Port**: `587`
- **Encryption**: `ExplicitTLS`
- **UseStartTLS**: `Yes`

**URL Format**: `smtp://${USER}:${PASSWORD}@smtp.gmail.com:587/?fromaddress=${FROM}&toaddresses=${TO}&encryption=ExplicitTLS&usestarttls=yes&timeout=30s`

**Note**: For Gmail, use an App Password if two-factor authentication is enabled.

#### AWS SES
- **Port**: `587`
- **Encryption**: `ExplicitTLS`
- **UseStartTLS**: `Yes`

**URL Format**: `smtp://${USER}:${PASSWORD}@email-smtp.us-east-1.amazonaws.com:587/?fromaddress=${FROM}&toaddresses=${TO}&encryption=ExplicitTLS&usestarttls=yes&timeout=30s`

#### Microsoft 365
- **Port**: `587`
- **Encryption**: `ExplicitTLS`
- **UseStartTLS**: `Yes`

**URL Format**: `smtp://${USER}:${PASSWORD}@smtp.office365.com:587/?fromaddress=${FROM}&toaddresses=${TO}&encryption=ExplicitTLS&usestarttls=yes&timeout=30s`

#### Generic (SSL)
- **Port**: `465`
- **Encryption**: `ImplicitTLS`
- **UseStartTLS**: `No`

**URL Format**: `smtp://${USER}:${PASSWORD}@smtp.example.com:465/?fromaddress=${FROM}&toaddresses=${TO}&encryption=ImplicitTLS&usestarttls=no&timeout=30s`

#### Generic (Plain)
- **Port**: `25`
- **Encryption**: `None`
- **UseStartTLS**: `No`

**URL Format**: `smtp://${USER}:${PASSWORD}@smtp.example.com:25/?fromaddress=${FROM}&toaddresses=${TO}&encryption=None&usestarttls=no&timeout=30s`

### Request Example
```bash
docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_NOTIFICATIONS=email \
  -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER="smtp.example.com:587" \
  -e WATCHTOWER_NOTIFICATION_EMAIL_FROM="sender@example.com" \
  -e WATCHTOWER_NOTIFICATION_EMAIL_USER="username" \
  -e WATCHTOWER_NOTIFICATION_EMAIL_PASSWORD="password" \
  nickfedor/watchtower
```

### Response
N/A
```

--------------------------------

### Control CPU Copy Mode for Container Recreation

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/arguments

Manages how CPU settings are copied when recreating containers, addressing Podman compatibility issues with CPU limits. Options are 'auto', 'full', and 'none'. Defaults to 'auto'.

```shell
Argument: --cpu-copy-mode
Environment Variable: WATCHTOWER_CPU_COPY_MODE
                Type: String
     Possible Values: auto, full, none
             Default: auto
```

--------------------------------

### Set Watchtower Logging Format

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/arguments_q=

Specify the logging format for Watchtower's console output using the `--log-format` or `-l` argument. This example sets the format to 'Pretty'.

```bash
docker run -d \
    -v /var/run/docker.sock:/var/run/docker.sock \
    nickfedor/watchtower \
    --log-format Pretty

```

--------------------------------

### Docker API Lifecycle Hooks

Source: https://watchtower.nickfedor.com/v1.14.2/advanced-features/lifecycle-hooks

Lifecycle hooks in Watchtower leverage the Docker exec API in a four-step process: creating an exec instance, starting its execution, capturing output, and monitoring its status.

```APIDOC
## Docker API Lifecycle Hooks

### Description
Lifecycle hooks utilize Docker's exec API through a sequence of operations to manage container commands during lifecycle events.

### Method
N/A (This describes a sequence of Docker API calls, not a single endpoint)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Docker API Sequence:
1. **Exec Creation**: `ContainerExecCreate` creates an exec instance with the specified command.
2. **Exec Start**: `ContainerExecStart` begins execution of the command.
3. **Output Capture**: `ContainerExecAttach` captures stdout/stderr output.
4. **Status Monitoring**: `ContainerExecInspect` monitors execution status and exit codes.
```

--------------------------------

### Conditional Backup Logic Based on Image Name in Bash

Source: https://watchtower.nickfedor.com/v1.14.2/advanced-features/lifecycle-hooks

Implements conditional logic to perform different backup actions based on the container's image name (e.g., 'postgres' or 'mysql'). This allows for database-specific backup procedures. Requires the WT_CONTAINER environment variable and jq to be installed.

```bash
#!/bin/bash
IMAGE=$(echo $WT_CONTAINER | jq -r '.image_name')
if [[ $IMAGE == *"postgres"* ]]; then
    echo "Running PostgreSQL-specific backup"
    pg_dump mydb > backup.sql
elif [[ $IMAGE == *"mysql"* ]]; then
    echo "Running MySQL-specific backup"
    mysqldump mydb > backup.sql
fi

```

--------------------------------

### Include Specific Containers with Docker Compose Label

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/container-selection

Define a service in docker-compose.yml with the 'com.centurylinklabs.watchtower.enable=true' label and ensure Watchtower is started with '--label-enable' to monitor this container for updates.

```docker-compose
version: "3"
services:
  someimage:
    container_name: someimage
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
```

--------------------------------

### Dockerfile: Notification System Hooks

Source: https://watchtower.nickfedor.com/v1.14.2/advanced-features/lifecycle-hooks_q=

This Dockerfile demonstrates the use of pre-check and post-check lifecycle hooks for sending notifications. The pre-check hook sends a 'Update cycle starting' message to a notification service before the update process begins. The post-check hook sends a 'Update cycle completed' message after the update cycle ends.

```Dockerfile
FROM alpine:latest

# Pre-check: Send start notification
LABEL com.centurylinklabs.watchtower.lifecycle.pre-check="curl -X POST -d 'Update cycle starting' http://notification-service/start"

# Post-check: Send completion notification
LABEL com.centurylinklabs.watchtower.lifecycle.post-check="curl -X POST -d 'Update cycle completed' http://notification-service/complete"


```

--------------------------------

### Migrate Legacy Email Notifications to Shoutrrr using Docker

Source: https://watchtower.nickfedor.com/v1.14.2/notifications/overview_q=

Demonstrates how to copy the output of the `watchtower notify-upgrade` command from a container to a local file for review and use with Shoutrrr.

```bash
docker cp <CONTAINER>:<FILE_PATH> ./watchtower-notifications.env
```

--------------------------------

### Signal Notification Attachments Example

Source: https://watchtower.nickfedor.com/v1.14.2/notifications/overview

Demonstrates how to send Signal notifications with base64-encoded attachments using the `shoutrrr send` command. The API server handles MIME type detection and file handling.

```shell
shoutrrr send "signal://localhost:8080/+1234567890/+0987654321" \
  "Message with attachment" \
  --attachments "base64data1,base64data2"
```

--------------------------------

### Configure Docker API Version for Watchtower

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/secure-connections_q=

Allows manual specification of the Docker API version. The default auto-negotiation is usually sufficient for most use cases.

```bash
Argument: --api-version
Environment Variable: DOCKER_API_VERSION
                Type: String
             Default: <Auto-negotiated>
```

--------------------------------

### Set Watchtower Maximum Log Level

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/arguments_q=

Configure the maximum log level for Watchtower output using the `--log-level` argument. Possible values range from 'panic' to 'trace'. This example sets it to 'debug'.

```bash
docker run -d \
    -v /var/run/docker.sock:/var/run/docker.sock \
    nickfedor/watchtower \
    --log-level debug

```

--------------------------------

### Enable Watchtower Debug Logging (Docker CLI)

Source: https://watchtower.nickfedor.com/v1.14.2/configuration/arguments

This command starts Watchtower with the `--debug` flag enabled, activating verbose logging. This is useful for troubleshooting and understanding Watchtower's internal operations.

```docker
docker run -d \
    --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    nickfedor/watchtower \
    --debug

```
Tokens:
Raw