Watchtower

A process for automating Docker container base image updates.

Quick Start

With watchtower you can update the running version of your containerized app simply by pushing a new image to the Docker Hub or your own image registry.

Watchtower will pull down your new image, gracefully shut down your existing container and restart it with the same options that were used when it was deployed initially. Run the watchtower container with the following command:

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

Watchtower is intended to be used in homelabs, media centers, local dev environments, and similar. We do not recommend using Watchtower in a commercial or production environment. If that is you, you should be looking into using Kubernetes. If that feels like too big a step for you, please look into solutions like MicroK8s and k3s that take away a lot of the toil of running a Kubernetes cluster.

Security Considerations

⚠️ Watchtower is designed for homelabs and local development, not production environments. Please review these security considerations before deploying:

Docker Socket Access

Watchtower requires access to /var/run/docker.sock, which grants full control over all containers on the host. This is equivalent to root access. Only run watchtower in trusted environments.

HTTP API

The HTTP API (--http-api-update) exposes container update controls:

• No TLS by default: API requests are sent over unencrypted HTTP
• Token authentication: Use a strong token (see --http-api-token flag help)
• Network exposure: Bind to localhost only in untrusted networks using Docker port mapping: -p 127.0.0.1:8080:8080
• Recommendation: Use a reverse proxy with HTTPS for any non-local access

Lifecycle Hooks

Lifecycle hooks (--enable-lifecycle-hooks) execute arbitrary commands inside containers:

• Command injection risk: Hooks run with container permissions
• User-supplied commands: Never use untrusted input in hook commands
• Recommendation: Carefully audit all lifecycle hook configurations

Registry Credentials

• Watchtower may handle registry credentials for pulling images
• Credentials are passed to the Docker daemon and may appear in logs at TRACE level
• Store credentials securely and use registry access tokens when possible

Reporting Security Issues

To report security vulnerabilities, please see our Security Policy.

This project follows the all-contributors specification. Contributions of any kind welcome!