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

By RunRacks Team · Published

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:latest can jump to a new major version without warning. Databases often cannot read data from an older major version without a migration.
  • image: postgres:16 follows bug and security fixes within version 16.
  • image: postgres:16.4 never 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:

Terminal
cd /opt/stacks/myapp
docker compose pull
docker compose up -d

pull 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:

Terminal
docker compose ps
docker compose logs --tail 50

When everything works, remove the old images:

Terminal
docker image prune

Roll 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:

Terminal
docker compose up -d

If you use a moving tag such as 16 or latest, note the image ID before each update so you can return to it:

Terminal
docker compose images

To pin the old version, use the digest shown by docker image inspect --format '{{index .RepoDigests 0}}' IMAGE_ID as the image: value.

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.

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:

YAML
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:

YAML
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.

Check it works

After a manual update, confirm the new image is in use:

Terminal
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 prune after updates, or see Free disk space with docker system prune.

Next steps

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.