Skip to content
API
Configuration
TLS

TLS

Overview

Watchtower’s HTTP API supports TLS (HTTPS) to encrypt traffic between clients and the API server.

By default, the HTTP API uses unencrypted HTTP. Enabling TLS ensures that all API requests, including authenticated ones, are protected against eavesdropping and man-in-the-middle attacks.

Using the HTTP API without TLS encryption is insecure and not recommended!

See the HTTP API overview for important security guidance.

Configuration

TLS is enabled by providing both of the following configuration options:

Both options must be set together. The server will use HTTPS when both are provided.

The certificate and key files must be accessible inside the Watchtower container, typically via a bind mount or Docker secret.

Walkthrough: Enabling TLS for the HTTP API

Step 1: Obtain a Certificate and Private Key

You need a valid X.509 certificate and matching private key.

Production Use

Use certificates from a trusted certificate authority such as:

  • Let’s Encrypt
  • Your organization’s internal CA
  • Cloud provider certificate services

Testing / Internal Use

You can generate a self-signed certificate for testing:

  • Generate a private key:

    openssl genrsa -out watchtower.key 2048

  • Generate a self-signed certificate (valid 365 days):

    openssl req -new -x509 -sha256 -key watchtower.key -out watchtower.crt -days 365 \
-subj "/C=US/ST=State/L=City/O=Organization/CN=watchtower.example.com"

Self-signed certificates will cause browser and client warnings.

For production or any environment where clients cannot easily trust the certificate, use certificates signed by a trusted CA.

Step 2: Prepare Files for the Container

Place watchtower.crt and watchtower.key in a directory on the host (e.g., /opt/watchtower/certs/).

Ensure proper permissions:

chmod 644 watchtower.crt
chmod 600 watchtower.key

Step 3: Mount and Configure Watchtower

Mount the certificate directory into the container, enable the metrics API (providing the /v1/metrics endpoint referenced in Step 4), and configure the TLS certificate and key paths.

services:
    watchtower:
        image: nickfedor/watchtower:latest
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
            - /opt/watchtower/certs:/certs:ro
        environment:
            - WATCHTOWER_HTTP_API_TOKEN=your-secure-token
            # Enables the /v1/metrics endpoint (used in Step 4)
            - WATCHTOWER_HTTP_API_ENDPOINTS=metrics
            - WATCHTOWER_HTTP_API_TLS_CERT=/certs/watchtower.crt
            - WATCHTOWER_HTTP_API_TLS_KEY=/certs/watchtower.key
        ports:
            - "8080:8080"
        restart: unless-stopped

Step 4: Connect Using HTTPS

Clients must use https:// when connecting:

curl -H "Authorization: Bearer your-secure-token" https://localhost:8080/v1/metrics

For self-signed certificates, you may need to:

  • Add the certificate to your system’s trust store, or
  • Use the --insecure / -k flag with tools like curl (not recommended for production)

Example with self-signed certificate:

curl -k -H "Authorization: Bearer your-secure-token" https://localhost:8080/v1/metrics

Important Considerations

  • The listening HTTP API Port remains the same; only the protocol changes to HTTPS.
  • All endpoints (including unauthenticated health probes) are served over HTTPS when TLS is enabled.
  • Authentication is still required for protected endpoints.
  • Ensure certificate files are mounted read-only (:ro) where possible.
  • Certificate rotation requires restarting the Watchtower container.
  • Hostname / SANs in the certificate must match how clients connect (especially important for production certificates).

Related Documentation

Last updated on
Authentication