Update Docker containers safely (manually or with Watchtower)
How to update Docker containers on a VPS without surprises. Pull and recreate with Compose, pin tags, roll back a bad update, and decide whether automatic updates with Watchtower suit your server.
- Intermediate
- Linux VPS
- 5 min read
Updating a container means replacing it with a new one built from a newer image. Your data survives because it lives in volumes, but the app itself can change in ways that break things. This guide shows a safe manual routine with Docker Compose, how to roll back, and the honest trade-offs of updating automatically with Watchtower.
Before you start
- A Linux VPS with Docker Engine and the Compose plugin.
- Apps defined in Compose files, with data in volumes or bind mounts, not inside containers.
- A recent backup of those volumes and of any database. See Back up and restore Docker volumes.
- The release notes of the app you are updating, especially for major versions.
Pin image tags
How you tag images decides what "update" means:
image: postgres:latestcan jump to a new major version without warning. Databases often cannot read data from an older major version without a migration.image: postgres:16follows bug and security fixes within version 16.image: postgres:16.4never changes until you edit the file.
For most apps, pin the major or minor version and update the number by hand when you are ready for a bigger jump. Commit the Compose file to Git so every change is recorded.
Update a stack manually
From the project folder:
cd /opt/stacks/myapp
docker compose pull
docker compose up -dpull downloads newer images for the tags in the file. up -d recreates only the containers whose image changed and leaves the rest running. Each recreated service is down for a few seconds.
Check the result:
docker compose ps
docker compose logs --tail 50When everything works, remove the old images:
docker image pruneRoll back a bad update
If you pinned an exact version, rolling back is a one-line change. Edit the tag back to the previous version and run:
docker compose up -dIf you use a moving tag such as 16 or latest, note the image ID before each update so you can return to it:
docker compose imagesTo pin the old version, use the digest shown by docker image inspect --format '{{index .RepoDigests 0}}' IMAGE_ID as the image: value.
Rolling back the app does not roll back its data. If the new version migrated the database schema, the old version may not start. Restore the backup taken before the update in that case.
What Watchtower does
Watchtower is a container that watches your other containers, pulls newer images for their tags on a schedule, and recreates them with the same options. It is convenient, but it changes running services without anyone watching.
The original containrrr/watchtower project was archived at the end of 2025 and no longer receives updates. Community forks continue the work. If you use Watchtower, choose a maintained fork, check its documentation for the current image name and options, and review it like any other software with access to the Docker socket.
When automatic updates make sense
Automatic updates are reasonable for:
- Stateless tools where a short outage does not matter, such as a status page or a log viewer.
- Images you build yourself, where each new tag has already passed your tests.
Avoid them for:
- Databases and anything that migrates data on upgrade.
- Apps with breaking changes between releases.
- Any production service where you need to know exactly what is running.
A middle path is to run Watchtower in monitor-only mode, so it notifies you of new images but does not update anything. You then update by hand at a time you choose.
Run Watchtower with care
A typical setup limits Watchtower to containers you have labelled. This example uses the common configuration options; confirm the image name and option names in your chosen fork's docs:
services:
watchtower:
image: WATCHTOWER_IMAGE
restart: unless-stopped
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
WATCHTOWER_LABEL_ENABLE: "true"
WATCHTOWER_CLEANUP: "true"
WATCHTOWER_SCHEDULE: "0 0 4 * * *"Replace WATCHTOWER_IMAGE with the maintained image you chose. Then label only the containers you want updated:
services:
uptime:
image: louislam/uptime-kuma:1
labels:
com.centurylinklabs.watchtower.enable: "true"The schedule uses six fields, with seconds first, so the example runs daily at 04:00.
Watchtower needs the Docker socket, which gives it root-level control of the server. Only run it from a source you trust.
Check it works
After a manual update, confirm the new image is in use:
docker compose images
docker inspect --format '{{.Created}}' $(docker compose ps -q app)The image tag or ID should match the new release, and the container creation time should be recent. Then open the app and run through its main tasks.
Troubleshooting
- `docker compose pull` finds nothing new: your tag is pinned to an exact version, or the publisher has not released one. Check the registry page.
- App fails after an update with a database error: the new version needs a migration step or a different major database version. Roll back and read the release notes.
- Watchtower updated a container you did not expect: label filtering is off. Set label-based enabling and recreate Watchtower.
- Disk fills up after many updates: old images remain. Run
docker image pruneafter updates, or see Free disk space with docker system prune.
Next steps
- Make updates near seamless: Near zero-downtime deploys with Docker Compose.
- Back up before every update: Back up and restore Docker volumes.
- Run your stacks on a Linux VPS.
Was this guide helpful?
Still stuck?
Ask RunRacks AI for a quick answer, or open a ticket and our team will take a look at your server.
Related guides
Docker & DevOps
Self-host Jellyfin with Docker and hardware transcoding
Install Jellyfin in Docker on a Linux VPS, mount your media library, publish it over HTTPS and switch on hardware transcoding with VAAPI or Intel Quick Sync.
- Intermediate
- Linux VPS
- 6 min read
Docker & DevOps
Deploy a Self-Hosted App with Docker Compose from Scratch
Write a compose.yaml, keep your secrets in .env, start the stack with docker compose up -d, then verify it and update it later without losing data.
- Beginner
- Linux VPS
- 7 min read
Docker & DevOps
Manage secrets and environment variables in Docker Compose
Keep API keys and database passwords out of your compose file using .env files, environment keys and Docker secrets, then confirm containers read them correctly.
- Intermediate
- Linux VPS
- 7 min read