My Jellyfin container sat on a version that was eight months old, and I only noticed because a new client refused to connect. That is the quiet problem with running Docker on a home NAS. Nobody sends you a reminder, the container just keeps working until one day it does not.
Watchtower is the tool a lot of home users reach for to fix exactly that. It watches your running containers, notices when a newer image lands on the registry, and swaps them out for you. No SSH sessions, no remembering to pull anything.
Before you turn it loose on your whole stack, though, it helps to understand what it is really doing under the hood, and where it can quietly ruin your weekend.
What Watchtower actually is
Watchtower is itself a Docker container. You run one small image, point it at your Docker socket, and it does the rest. It is not a service you install on the NAS operating system, and it is not tied to Synology or QNAP in any way.
Once running, it checks the registry (usually Docker Hub) on a schedule for each container it is watching. When it sees that the image tag you are using, say lscr.io/linuxserver/jellyfin:latest, now points at a newer image digest than the one you have, it acts.
The key word is digest. Watchtower does not care about version numbers you can read. It compares the cryptographic hash of your local image against the one on the registry. If they differ, it considers the container out of date.
How an update actually happens
The process is more careful than most people assume. When Watchtower decides a container is stale, it does not edit the running container in place. It rebuilds it from scratch using the settings the old one had.
Here is the sequence, step by step:
- It pulls the new image from the registry to local storage.
- It gracefully stops the old container (sending SIGTERM, then SIGKILL after a timeout, 10 seconds by default).
- It reads the old container's configuration: its volumes, port mappings, environment variables, and network settings.
- It creates a brand new container from the new image using that exact same configuration.
- It starts the new container and removes the old one.
This is why your data survives. Anything you stored in a named volume or a bind mount, like /volume1/docker/jellyfin/config on a Synology, is untouched. Only the software layer gets replaced.
The whole thing usually takes 20 to 60 seconds per container, most of which is the image download. On a decent home connection, a single app update is barely a blip.
One detail catches people out. During those few seconds, the app is genuinely offline, so if you are streaming a movie when Watchtower fires, the stream drops. That is another reason to run it at a quiet hour, like 4am, rather than mid-evening.
Setting it up on a home NAS
The classic setup is a single command, or a short compose file. On most NAS boxes you would drop this into a docker-compose.yml and bring it up through Portainer or the built-in Container Manager.
A minimal compose entry looks like this: it mounts the Docker socket, sets a schedule, and turns on cleanup of old images so your storage does not fill with dead layers.
By default Watchtower checks every 24 hours. You can change that with a cron-style schedule, but honestly, daily is plenty for a home setup. Checking every few minutes just hammers the registry for no benefit and can get you rate-limited by Docker Hub.
The official documentation for the socket mount and schedule flags lives in the Docker run reference if you want to sanity-check any option you copy from a forum.
The part nobody warns you about
Auto-updating everything sounds great right up until an update introduces a breaking change and you were asleep when it happened.
The most common way this bites people is the latest tag. When you run an image as :latest, you are telling Watchtower to grab whatever the maintainer pushes next, including major version jumps that change config formats or drop features.
I lost an evening to this with a Nextcloud container. An overnight update rolled it to a major release that required a manual database migration, and the app came up throwing Internal Server Error with nothing useful in the browser. The data was fine, but the app was down until I read the upgrade notes.
Which containers to automate, and which to pin
The trick is not to run Watchtower everywhere or nowhere. Split your stack into things where a surprise update is annoying versus things where it is a disaster.
| Container type | Auto-update? | Why |
|---|---|---|
| Stateless apps (Uptime Kuma, dashboards) | Yes | Low risk, easy to roll back, no data to corrupt |
| Media servers (Jellyfin, Plex) | Cautiously | Pin to a major version tag, not latest |
| Databases (MariaDB, Postgres) | No | Major bumps can break data files |
| Reverse proxies (Nginx Proxy Manager) | Cautiously | A bad update can lock you out of everything behind it |
You can tell Watchtower to ignore specific containers by adding a label, com.centurylinklabs.watchtower.enable=false, to the ones you want to pin. That way one Watchtower instance can update the safe stuff and leave the fragile stuff alone.
Pinned tags are your safety net
The single best habit here has nothing to do with Watchtower itself. It is using specific image tags instead of latest.
If you run Jellyfin as :10.9 instead of :latest, Watchtower will happily install patch updates within that line but will never jump you to a whole new major version overnight. You get security fixes without the config-breaking surprises.
When a new major version comes out, you update the tag yourself, on a Saturday morning, with the release notes open. That is the version bump you actually want to be awake for.
Some images make this even easier by publishing tags like :2 or :2.4 alongside :latest. Pinning to the major line gives you a good middle ground: automatic security and bug fixes within that version, and a manual, deliberate step whenever you cross into the next major release.
So should you actually use it
For a home NAS running a handful of hobby containers, Watchtower earns its keep. Left on a daily schedule, pointed only at the low-risk apps, with real version tags instead of latest, it quietly keeps your stack patched without you thinking about it.
Where it goes wrong is treating it as fire-and-forget for the whole stack. Databases stay manual, anything critical gets a pinned major tag, and you keep notifications on so a bad night never turns into a bad week.
Set it up that way and the eight-month-old container problem simply stops happening. That alone is worth the ten minutes of setup.
Frequently asked questions
Will Watchtower delete my container data when it updates?
No. Watchtower reuses the same volumes, bind mounts, environment variables, and port mappings from the old container. Anything stored in a named volume or a host path like /volume1/docker/app stays exactly where it was. Only the application image itself is swapped for the newer version.
How often does Watchtower check for updates?
By default it checks every 24 hours. You can set a custom cron-style schedule, but daily is plenty for a home NAS. Checking too frequently just adds registry traffic and can trigger Docker Hub rate limits without giving you any real benefit.
Can I stop Watchtower from updating certain containers?
Yes. Add the label com.centurylinklabs.watchtower.enable=false to any container you want it to skip. This lets a single Watchtower instance auto-update your safe, stateless apps while leaving databases and other fragile containers pinned and untouched.
Why is using the :latest tag risky with Watchtower?
The latest tag pulls whatever the maintainer pushes next, including major version jumps that can change config formats or require manual migrations. Pinning to a specific version like :10.9 lets Watchtower apply safe patch updates without dragging you across a breaking major release overnight.
Does Watchtower work on Synology and QNAP NAS boxes?
Yes. Watchtower runs as an ordinary Docker container, so it works anywhere Docker or Container Manager runs, including Synology DSM and QNAP Container Station. It talks to the Docker socket, not the NAS operating system, so it is not tied to any specific brand.
How do I roll back if an update breaks an app?
If you pinned a version tag, change the tag back to the previous version in your compose file and recreate the container. Because your data lives in volumes, this usually restores the app cleanly. This is exactly why keeping notifications on matters, so you know which container changed and can revert quickly.
