docs: Better communicate updates are restricted to the image tag used

[polarathene]

Describe the bug

Watchtower detects an image update by monitoring updates to the exact image tag of a running container. The docs don't appear to explain this well? Digging through issues (or source code) is presently required for the clarification.

To a degree one could infer the logic, as watchtower is not modifying the configuration / command to adjust any tag? Thus the pull update to restart a container with wouldn't support a different tag (which I don't think was ever mentioned in similar issues requesting semver support).

I think it would be wise to improve documentation of the update mechanism, clarifying that an image update is detected by monitoring its associated tag at the registry pointing to a new image?

Referencing docs

Take the start of the project README as an example:

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.

That's inaccurate if the tag changes. The implicit context here is likely the latest tag, but watchtower is not restricted to that.

Likewise the docs introduction page is similarly vague:

Watchtower is an application that will monitor your running Docker containers and watch for changes to the images that those containers were originally started from.
If watchtower detects that an image has changed, it will automatically restart the container using the new image.

Changes to an image the container was started from is a tad vague. The example that follows then demonstrates an image update without any explicit tag present.

Valid use-case that would benefit

Clarifying this part of the docs is historically most relevant to those repeated requests for semver support. The common advice is to follow best practice of tagging images for semver, via multiple tags such as with this hierarchy:

• latest (latest major)
• 1 (latest minor, for a given major)
• 1.2 (latest patch of a major.minor)
• 1.2.3 (while less likely to receive an update, still possible depending on image maintenance policy)
   
  For third-party images that are published without the multi-tag semver practice, but still use semver in tags:
• This is not a feature watchtower plans to support (as some reports had discovered, there's more overhead / complexity involved).
• Alternative solutions like WUD (whats-up-docker) cater to that (some images have tag variants as a prefix/suffix, not just semver only tags).
  • Default behaviour does not update image, so no image pull for notification only watching. Only pulls an image when using an update trigger.
  • Supports tag filtering via container label.
  • Supports updating to new tag in compose.yaml as an update trigger.
  • Not always a viable alternative to watchtower.

Steps to reproduce

Observe that the docs don't explain the update mechanism is locked to the image tag, only "changes to the image".

Expected behavior

Clearer communication of what to expect of watchtower image updates, notably when it comes to tags that aren't the implicit default. Feature relies on mutable tags (eg multi-tag semver to subscribe to updates of a semver range).

Screenshots

No response

Environment

N/A

Your logs

N/A

Additional context

I maintain docs for a Docker image focused project and was recently revising a community contributed page advising watchtower.

Not knowing much about the project, I wanted to double-check the advice we document wasn't going to cause any surprises like unexpected upgrades to new major releases with breaking changes, but the watchtower docs did not communicate this concern clearly.

---

Multiple issues requesting support for semver tag updates in the past better communicated the monitoring / update behaviour than the current docs do:

If you want to follow semantically versioned tags, you'll need to take care of this yourself.
Watchtower tracks one tag, most commonly latest.

• Source

Watchtower works by simply pulling the same image/tag, and comparing the content.
Providing your image follows the guidelines above, this works very well.

• Source

Currently, watchtower only looks at hash changes for the label you've started the container with.

• Source

If you are in control of the image repo, you could just put multiple tags on your images, like:
myapp:1 myapp:1.3 myapp:1.3.4 or myapp:v1.3.4 myapp:stable
This is the de facto standard of doing semver releases on dockhub afaik.

• Source

The best would be if you follow the guidelines of the docker official images for tags and aliases.
Following that you could just use e.g. the tag 2.3 and you automatically stay on the newest patch version of 2.3. 2.3 is essentially an alias for 2.3.0, 2.3.1, 2.3.2,... as soon as they get released.

• Source

When I started using watchtower, I was very much hoping that this is a feature already available.
Relying on mutable tags is… eh :-(

• Source

[github-actions]

Hi there! 👋🏼 As you're new to this repo, we'd like to suggest that you read our code of conduct as well as our contribution guidelines. Thanks a bunch for opening your first issue! 🙏

[JRHemmen]

Looked around everywhere for documentation to clarify just this, thank you! Some kind of ability to update based on tags (maybe watchtower could edit the underlying compose and pull a new given version?) would be huge. Though not sure how filtering through repos with multiple tag patterns (branch-hash, semver, dates, etc.) would work.

I had been attempting to write something similar myself but running into issues with recreating sibling containers.

[polarathene]

You're welcome!

Given there's been no activity on this project (and at a glance some others by the org) since Jan, the status of the project is not reassuring 😓

Some kind of ability to update based on tags (maybe watchtower could edit the underlying compose and pull a new given version?) would be huge.

See the alternative I linked to above WUD. It can update the compose config and appears to actively maintained still.

Though not sure how filtering through repos with multiple tag patterns (branch-hash, semver, dates, etc.) would work.

Also see WUD mention. You can assign labels to the service that add filtering rules.