Skip to content

Registry Mirrors

Registry mirrors provide alternative locations for pulling Docker images, useful when access to the default registry is slow, unreliable, or restricted by network policy. Watchtower uses these mirrors when checking whether containers need updates, ensuring it can detect new images even when the primary registry is unreachable.

Overview

When the Docker daemon is configured with registry mirrors, Watchtower automatically detects and uses them during its update checks. This means:

  • Digest comparisons — Watchtower fetches image manifests from mirrors before falling back to the canonical registry, so it can detect updates even when the primary registry is inaccessible.
  • All registries supported — Global mirrors apply to all image registries (Docker Hub, GHCR, private registries, etc.).

Note

Mirror support in Watchtower covers digest comparison only — determining whether a newer image exists. The actual image pull is handled by the Docker daemon, which already uses configured mirrors natively.

Configuring Registry Mirrors

Registry mirrors are configured in the Docker daemon, not in Watchtower itself.

Configuration File

  • Linux: /etc/docker/daemon.json
  • Windows: C:\ProgramData\docker\config\daemon.json
  • Rootless mode: ~/.config/docker/daemon.json

After making changes, restart the daemon:

Linux with systemd
sudo systemctl restart docker

Configuration Format

Global mirrors apply to all image registries. Add them under the registry-mirrors key:

/etc/docker/daemon.json
{
    "registry-mirrors": [
        "https://mirror.example.com"
    ]
}

When multiple mirrors are listed, they are tried in order until one succeeds.

Command-Line Configuration

Mirrors can also be set via the dockerd command line:

dockerd --registry-mirror https://mirror.example.com

How Watchtower Uses Mirrors

When checking if a container's image has been updated, Watchtower resolves the mirror to use in this order:

  1. Configured mirrors — The global mirror list from the Docker daemon is tried first.
  2. Canonical registry — If all mirrors fail, Watchtower falls back to the original registry (e.g., index.docker.io).

The first mirror to successfully respond with the image manifest wins. This means a fast, nearby mirror is preferred over a distant canonical registry.

Configuration Examples

Single Global Mirror

A single mirror used for all registries:

/etc/docker/daemon.json
{
    "registry-mirrors": [
        "https://docker-mirror.company.com"
    ]
}

Multiple Mirrors with Redundancy

Mirrors are tried in the order listed. If the first is unreachable, the next is used:

/etc/docker/daemon.json
{
    "registry-mirrors": [
        "https://primary-mirror.company.com",
        "https://backup-mirror.company.com"
    ]
}

Corporate Proxy Environment

When using internal mirrors that may use self-signed certificates:

/etc/docker/daemon.json
{
    "registry-mirrors": [
        "https://harbor.internal.company.com"
    ],
    "insecure-registries": [
        "harbor.internal.company.com"
    ]
}

Troubleshooting

Mirrors Not Being Used

  1. Verify daemon configuration — Confirm that /etc/docker/daemon.json contains valid JSON and the Docker daemon has been restarted since the last change.

  2. Enable debug logging — Run Watchtower with debug logging to see mirror resolution in action:

    docker run -d --name watchtower \
-e WATCHTOWER_DEBUG=true \
-v /var/run/docker.sock:/var/run/docker.sock \
ghcr.io/sidneyojr/watchtower

    Look for log output containing Resolved registry mirror configuration. 3. Check network access — Ensure the host can reach the mirror URLs (e.g., curl -I https://mirror.example.com/v2/). 4. Verify mirror content — Confirm the mirror is operational and has the required images.

Authentication Issues

If a mirror requires authentication, configure credentials in the Docker daemon (e.g., docker login). Watchtower uses the same credentials for mirrors as for the canonical registry.

SSL/TLS Errors

For mirrors using self-signed or internal CA certificates, add them to the insecure-registries list:

{
  "insecure-registries": ["internal-mirror.company.com"]
}

Warning

Insecure registries accept HTTPS with untrusted certificates. Only use this for internal mirrors under your control.