Docker Secrets¶

Overview¶

Watchtower supports the use of Docker Secrets to provide a way for using sensitive values without exposing them as environment variables.

The following supported configuration options allow for users to reference a filepath instead of directly referencing the secret value (e.g. WATCHTOWER_HTTP_API_TOKEN=/run/secrets/api_token instead of WATCHTOWER_HTTP_API_TOKEN=secret_token).

Watchtower will then check whether the provided value is a path to an existing file on disk. Upon successful validation, the contents of the file are read and used as the value instead.

Supported Configuration Options¶

Configuration Option	Deprecated
HTTP API Token	No
HTTP API Events Token	No
Notification URL	No
Email Server Password	Yes
Gotify Token	Yes
Microsoft Teams Hook	Yes
Slack Hook URL	Yes

Watchtower v2 Legacy Notification Deprecation

Deprecated notification configuration options will be removed with the release of Watchtower v2.

Use the the NOTIFICATION URL with the appropriate Shoutrrr URL scheme instead.

Note

For the Notification URL option, when a value is a path to a file, each non-empty line in the file is treated as a separate notification URL.
This file-based support works with any mechanism that can make a file available inside the container at runtime.
You specify the path to the file inside the container (e.g. /run/secrets/http_api_token).

Examples¶

HTTP API Token¶

Provide the HTTP API Token from a file.

Docker ComposeDocker CLI

services:
    watchtower:
        image: ghcr.io/sidneyojr/watchtower:latest
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
        secrets:
            - api_token
        environment:
            - WATCHTOWER_HTTP_API_TOKEN=/run/secrets/api_token
            # Enable an endpoint that requires the token
            - WATCHTOWER_HTTP_API_ENDPOINTS=metrics
        ports:
            - "8080:8080"
        restart: unless-stopped

secrets:
    api_token:
        file: ./secrets/api_token.txt

docker run -d \
    --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v $(pwd)/secrets/api_token.txt:/run/secrets/api_token:ro \
    -e WATCHTOWER_HTTP_API_TOKEN=/run/secrets/api_token \
    -e WATCHTOWER_HTTP_API_ENDPOINTS=metrics \
    -p 8080:8080 \
    --restart unless-stopped \
    ghcr.io/sidneyojr/watchtower

HTTP API Events Token¶

Provide the HTTP API Events Token from a file.

Docker ComposeDocker CLI

services:
    watchtower:
        image: ghcr.io/sidneyojr/watchtower:latest
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
        secrets:
            - events_token
        environment:
            - WATCHTOWER_HTTP_API_EVENTS_TOKEN=/run/secrets/events_token
            - WATCHTOWER_HTTP_API_ENDPOINTS=events
        ports:
            - "8080:8080"
        restart: unless-stopped

secrets:
    events_token:
        file: ./secrets/events_token.txt

docker run -d \
    --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v $(pwd)/secrets/events_token.txt:/run/secrets/events_token:ro \
    -e WATCHTOWER_HTTP_API_EVENTS_TOKEN=/run/secrets/events_token \
    -e WATCHTOWER_HTTP_API_ENDPOINTS=events \
    -p 8080:8080 \
    --restart unless-stopped \
    ghcr.io/sidneyojr/watchtower

Notification URL¶

Provide the Notification URL value(s) from a file. The file may contain one or more Shoutrrr URLs (one per line).

Docker ComposeDocker CLI

services:
    watchtower:
        image: ghcr.io/sidneyojr/watchtower:latest
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
        secrets:
            - notification_url
        environment:
            - WATCHTOWER_NOTIFICATION_URL=/run/secrets/notification_url
        restart: unless-stopped

secrets:
    notification_url:
        file: ./secrets/notification_url.txt

docker run -d \
    --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v $(pwd)/secrets/notification_url.txt:/run/secrets/notification_url:ro \
    -e WATCHTOWER_NOTIFICATION_URL=/run/secrets/notification_url \
    --restart unless-stopped \
    ghcr.io/sidneyojr/watchtower