watchtower

Watchtower — the maintained fork

Automatic base-image updates for Docker containers. A drop-in replacement for containrrr/watchtower, which is no longer maintained upstream.

Documentation · Why this fork? · Changelog

TL;DR

• What it is: a small Go daemon that polls the Docker socket, checks registries for new image digests, and recreates stale containers with the same config (volumes, networks, env, command).
• Who it's for: homelabs, self-hosted stacks, media centers, dev environments — anywhere a running Kubernetes cluster would be overkill.
• Who it's not for: production workloads that need staged rollouts, canaries, or rollback. Use Kubernetes (or k3s / MicroK8s) for that.
• Images: docker.io/openserbia/watchtower and ghcr.io/openserbia/watchtower (multi-arch: amd64, arm64, arm/v6, arm/v7, 386, riscv64).
• Module path: github.com/openserbia/watchtower.

Quick start

Requirements: Docker Engine 20.10 or newer. Watchtower auto-negotiates the API version, so older daemons may work but aren't tested.

docker run --detach \
    --name watchtower \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    openserbia/watchtower

That's it — Watchtower polls every 24h by default and updates any container it can see. To scope it, opt containers in with a label:

docker run --label com.centurylinklabs.watchtower.enable=true my-app:latest
docker run -v /var/run/docker.sock:/var/run/docker.sock \
    openserbia/watchtower --label-enable

docker-compose

services:
  watchtower:
    image: openserbia/watchtower:latest
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command:
      - --interval=60
      - --cleanup
      - --label-enable

Full flag reference, notification setup, lifecycle hooks, HTTP API, and metrics all live on the docs site.

Why this fork

containrrr/watchtower stopped accepting changes in late 2024. This fork keeps it alive with a modern toolchain (Go 1.26, golangci-lint v2, Devbox-pinned CI) and extends the same feature set across four axes:

• Fixes real-world upstream bugs left unmerged when the project was archived — #966 (--cleanup deletes the replacement image), #1217 (nil-pointer panic on GC'd source image), #1413 (No such image loop that wedges the container).
• Safer updates — opt-in --health-check-gated waits for the replacement container to report healthy and automatically rolls back to the previous image on failure, with per-container label overrides and a post-rollback cooldown that prevents thrash.
• Hardened network layer — bounded exponential backoff on registry flakes, an in-memory bearer-token cache, strict TLS by default (removing upstream's blanket InsecureSkipVerify), constant-time bearer-token comparison, and opt-in --insecure-registry / --registry-ca-bundle for self-signed registries.
• Operational visibility — ship-ready Grafana dashboard + Prometheus alerts, a GET /v1/audit JSON endpoint for post-deploy verification, --http-api-metrics-no-auth for trusted-network scraping, and ~20 new metrics covering every HTTP-facing surface (request counts by status/endpoint/host/outcome, retry counters, Docker API errors, bearer-cache hit rate, poll-duration histogram, and more).

Drop-in compatible — same CLI flags, labels (com.centurylinklabs.watchtower.*), HTTP API, and notification backends. Swap the image name and you're done. Migration diff, full comparison table, and roadmap: Why this fork?.

Verifying a release

# Binary checksums
sha256sum -c watchtower_<version>_checksums.txt --ignore-missing

# Image provenance
docker inspect openserbia/watchtower:latest \
    --format '{{ index .Config.Labels "org.opencontainers.image.revision" }}'

Security

Report vulnerabilities via GitHub Security Advisories — this opens a private thread with the maintainers. Please do not file public issues for security bugs. See SECURITY.md for scope and policy.

Contributing

devbox shell                 # reproducible toolchain (Go 1.26, golangci-lint v2, go-task)
devbox run -- task lint      # 0 findings required
devbox run -- task test      # Ginkgo suites with -race
devbox run -- task build     # ./build/watchtower

See CONTRIBUTING.md for PR expectations and CLAUDE.md for an architectural tour tuned for AI coding assistants (and handy for humans too).

License

Apache 2.0. Originally © containrrr authors; fork maintained under the same license. See LICENSE.md.