Watchtower Docker Updates: Compatibility, Checks and Recovery

Docker makes it convenient to run home services, but image updates still need a plan. Watchtower was built to check container images and recreate selected containers when their tags change. Understanding its scope, compatibility and recovery requirements is more useful than assuming every automated update will be trouble-free.

Check Project Status Before Installing

The original upstream Watchtower repository was archived on 17 December 2025. Its repository is now read-only. This article explains the established tool and a controlled workflow for existing compatible installations. Archive status matters when deciding who will maintain the updater that has access to your Docker host.

There are upstream reports of Docker 29 rejecting Watchtower's older API client. An error mentioning client API 1.25 and a minimum supported API of 1.44 is a compatibility problem, not proof that a container label is wrong. Check your engine version and the actual updater logs before relying on it. Do not weaken the daemon's security settings just to make an archived updater connect.

What Docker Updates Actually Change

If containers are new to you, our Docker article covers the basics, and Docker's website links to installation resources. An image supplies application files, while the running container also has configuration and attached storage. Updating an image does not automatically update the host operating system, your Compose file, reverse proxy configuration or a separate database service.

Containers share the host kernel rather than each containing a complete independent operating system. Persistent application data normally belongs in volumes or bind mounts. Before any update, identify those paths: a new container can start successfully while using an empty directory if its storage was configured incorrectly.

Image tags are names that can be republished; a digest identifies particular image content. An updater watching a fixed tag checks that tag, rather than deciding whether a different major-version tag is an appropriate upgrade. Read the application's upgrade notes to find out whether its image, database and configuration must change together. See Docker's image-pull documentation for tags and digests.

What Watchtower Does and Does Not Guarantee

Watchtower uses Docker's API to inspect containers, check their image references and, when configured to update, stop and recreate selected containers. That can interrupt connections. It does not guarantee zero downtime, working database migrations, or a successful application-level recovery. A started process is not the same thing as a tested login, file upload or completed backup.

By default, its scope is broad. Restrict it to services you have deliberately selected. Monitoring mode avoids container replacement, but the argument reference explains that it may still pull images and invoke configured lifecycle hooks. It should not be described as a completely passive or zero-risk scan.

Choose Which Services Can Be Automated

Updates can fix vulnerabilities and defects, but a newer image alone does not prove your service is secure. Access control, host patches, credentials and exposed ports remain your responsibility. Conversely, indefinitely freezing every image leaves known defects in place. A sensible home setup separates finding available updates from approving changes to important services.

Service situation	Reasonable update approach	Acceptance check
Disposable stateless demo	Candidate for a controlled automated trial	Open its page and test the function you actually use.
Photos, documents or application database	Read release notes and take an application-consistent backup before a planned update	Check existing records and perform a harmless new operation.
DNS, remote access or reverse proxy	Use a maintenance window with an independent recovery path	Test name resolution and access from another device.
Multi-container application with prescribed upgrade order	Follow its documented coordinated upgrade	Check all dependent services and application logs.

This table is a planning aid, not a compatibility certification for particular applications. Consider who uses each service, whether you can reach the host without it, and how long recovery would take. Start with the least consequential service and expand only after you have observed the entire process.

Understand Docker Socket Access

The usual Watchtower setup mounts /var/run/docker.sock. On a standard rootful Docker installation, access to that API is highly privileged and can affect the host. A read-only filesystem mount of the socket is not an API authorization policy. Treat the updater as trusted administrative software, and do not publish an unauthenticated Docker API to the network. Docker's security documentation explains the daemon's trust boundary.

The examples below assume Linux containers on a compatible local Docker engine and a shell with permission to use Docker. Rootless Docker, remote engines and Windows-container hosts have different socket or connection arrangements. Confirm your environment instead of copying the socket path into an unrelated deployment.

Start with One Container and One Check

First inspect the engine and Compose versions. Then list running container names so you can choose the exact target:

docker version
docker compose version
docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'

The next command assumes you already have a disposable container called homelab-demo. Replace that name with your chosen test container. The image is the upstream 1.7.1 release; pinning it makes the example explicit and does not resolve its engine compatibility limitations.

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower:1.7.1 \
  --run-once --monitor-only homelab-demo

Read the terminal output. Verify that the selected container was scanned and that no API, registry or authentication error occurred. A normal exit with no available update is not evidence that replacement and recovery have been tested. If you encounter the engine API problem described earlier, stop here and use a maintained update workflow appropriate to your engine.

Use Explicit Selection for a Scheduled Trial

For an existing compatible installation, add this label beneath the selected application's service in its own Compose file, then recreate that service through its normal deployment process:

labels:
  com.centurylinklabs.watchtower.enable: "true"

Do not place it only on Watchtower; it identifies the application containers you intend to scan. Preserve the application's existing labels and settings. The container-selection documentation describes opt-in labels and how name filters combine with them.

In a separate folder, save the following as compose.yaml. Use this instead of starting a second overlapping Watchtower instance. The initial mode checks selected containers without replacing them.

services:
  watchtower:
    image: containrrr/watchtower:1.7.1
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      WATCHTOWER_LABEL_ENABLE: "true"
      WATCHTOWER_MONITOR_ONLY: "true"
      WATCHTOWER_POLL_INTERVAL: "3600"
      WATCHTOWER_CLEANUP: "false"

docker compose config --quiet
docker compose up -d
docker compose logs --tail=100 watchtower

The interval is one hour. Keep polling or a cron schedule as separate alternatives; do not set both. If using a schedule later, check its seconds field and timezone rather than assuming it follows your laptop clock. Cleanup is disabled here so previous images are not automatically discarded after replacement; watch disk space and remove images deliberately after your recovery window.

Notifications Need Their Own Test

The example records activity in logs; it has no email or phone notification destination. Configure a supported Shoutrrr service URL using WATCHTOWER_NOTIFICATION_URL if you want messages. Use the upstream notification instructions for that service's syntax and protect credentials outside a public Compose file.

A plain HTTP notification endpoint is not interchangeable with every Shoutrrr service URL. Likewise, an obscure public topic name is not a substitute for authentication when notifications contain private host information. Confirm a startup or test message arrives, then confirm an actual scan result. Review the template: a notification rule that reports completed replacements may not tell you about every available update during monitoring mode.

Keep a simple record containing the container name, old image reference, discovered update, backup location and result of the acceptance check. That record makes repeated checks useful: you can see whether a failure began with an update or was already present.

Perform One Controlled Update and Plan Recovery

Before enabling replacement, read the selected application's release notes, back up its data using its documented method, and save the Compose file and relevant configuration. Record the exact old image and its identifier:

docker inspect homelab-demo --format '{{.Config.Image}} {{.Image}}'
docker image inspect $(docker inspect homelab-demo --format '{{.Image}}') --format '{{json .RepoDigests}}'

Replace the example name consistently. A repository digest is helpful when available; a local image ID alone is not a portable backup. Keep the old image or a retrievable digest and a matching data backup. A newer application may migrate its database, in which case returning to an older image without restoring compatible data can fail.

For the disposable trial, stop the scheduled updater first with docker compose stop watchtower in its folder. After the compatibility and backup checks, run the same one-shot command with --monitor-only removed. Observe the restart, inspect application logs and test its actual function. Re-enable the scheduled checker only when you have finished assessing the result.

If the service fails, stop automatic replacement and use the application's normal deployment file to select the saved image reference. Restore data only through its documented recovery process. Check the service from another device, not just the Docker status column. Do not use docker compose down -v as an update or rollback shortcut: removing persistent volumes is a different, destructive operation.

Conclusion

Watchtower can explain how automated container replacement works, and existing compatible installations benefit from explicit selection, logs and rehearsed recovery. Its archived upstream status changes the decision for a new setup. Whether you use an updater or review images manually, keep the same discipline: discover the change, verify compatibility, preserve recoverable data, and test the application after deployment.