Back to tutorials
Tutorial

Docker Compose Auto-Updates With Watchtower on a VPS

Set up Watchtower Docker Compose auto-updates on a VPS with schedules, labels, notifications, and safe rollback steps.

By Anurag Singh
Updated on Nov 20, 2026
Category: Tutorial
Share article
Docker Compose Auto-Updates With Watchtower on a VPS

Auto-updating containers sounds easy. Then you wake up to a failed pull. Or an app quietly changed defaults. This tutorial shows how to run Watchtower Docker Compose updates on a production VPS with guardrails. You’ll use label-scoped updates, a maintenance window, notifications, and a rollback workflow you can run fast.

The examples assume Ubuntu 24.04+ or Debian 12+ (AlmaLinux/Rocky work too, with minor package differences). Everything runs on a single host. That fits most self-hosted stacks: WordPress sidecars, reverse proxies, analytics, wikis, and small internal tools.

What you’ll build (and what you should not auto-update)

You’ll run Watchtower as a container that:

  • Checks for new images on a schedule (not continuously)
  • Updates only the services you explicitly label
  • Sends a notification for each update attempt
  • Keeps rollback straightforward when an update misbehaves

Be picky about what you auto-update. Good candidates:

  • Stateless services (UIs, API containers that read config from env/files)
  • Reverse proxies (Nginx, Caddy, Traefik) if you pin major versions
  • Internal tools where a short outage is acceptable

Use extra caution with:

  • Databases (PostgreSQL, MariaDB/MySQL): don’t let major versions roll automatically
  • Apps that run schema migrations you haven’t tested
  • Anything without a healthcheck or a fast rollback plan

If you’re running multiple production services and want someone else handling OS patching, Docker maintenance, and incident response, managed VPS hosting keeps updates predictable while you still run your own stack.

Prerequisites on your VPS

  • A VPS or dedicated server with SSH access and sudo
  • A domain already pointed at your server (recommended for real apps)
  • Docker Engine + Docker Compose plugin installed

If you’re starting from scratch, begin with a sensible baseline.

A small-to-mid stack typically fits well on 2 vCPU / 4 GB RAM with NVMe.

See HostMyCode VPS options if you need predictable resources and root access.

Verify Docker and Compose

docker --version
docker compose version

In 2026, aim for Docker Engine 25+ and the Compose plugin 2.2x+.

If you’re behind, upgrade first. Then automate.

Create a dedicated directory for your stack

sudo mkdir -p /opt/stack
sudo chown -R $USER:$USER /opt/stack
cd /opt/stack

Step 1: Write a Compose file with explicit labels (safe by default)

The most common Watchtower failure mode is letting it update everything on the host.

Don’t do that.

Use labels so only the services you choose get touched.

Create /opt/stack/docker-compose.yml:

services:
  whoami:
    image: traefik/whoami:latest
    container_name: whoami
    restart: unless-stopped
    ports:
      - "8080:80"
    labels:
      - "com.centurylinklabs.watchtower.enable=true"

  watchtower:
    image: containrrr/watchtower:latest
    container_name: watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      # Use label-based inclusion; everything else is ignored.
      - WATCHTOWER_LABEL_ENABLE=true

      # Only check on a schedule (see Step 2).
      # WATCHTOWER_SCHEDULE will be added later.

      # Clean up old images after updating.
      - WATCHTOWER_CLEANUP=true

      # Avoid running two update cycles at once.
      - WATCHTOWER_INCLUDE_RESTARTING=true
      - WATCHTOWER_ROLLING_RESTART=true

      # Optional: reduce noise.
      - WATCHTOWER_NOTIFICATIONS_LEVEL=info

    labels:
      # Do NOT let Watchtower update itself automatically.
      # You want to change automation intentionally.
      - "com.centurylinklabs.watchtower.enable=false"

Bring it up

docker compose up -d

Verify it’s running

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

docker logs --tail=50 watchtower

Right now, Watchtower should be running but not updating anything. That’s intentional.

Set the rules first. Then enable automation.

If you also run an Nginx reverse proxy, it helps to have a clean proxy baseline.

HostMyCode’s tutorial on reverse proxy setup with Nginx and SSL pairs well here (even if you’re proxying something other than ComfyUI).

Step 2: Add a maintenance window schedule

Auto-updates work best inside a window you picked.

Don’t let them fire at random times.

Watchtower supports cron-style scheduling. Choose a low-traffic time. Example: every day at 03:20 server local time.

Edit /opt/stack/docker-compose.yml and add:

    environment:
      - WATCHTOWER_LABEL_ENABLE=true
      - WATCHTOWER_SCHEDULE=0 20 3 * * *

Watchtower’s schedule uses six fields (it includes seconds): sec min hour day month weekday.

The example above runs at 03:20:00 daily.

Apply the change

docker compose up -d

Confirm the schedule is active

docker inspect watchtower --format '{{json .Config.Env}}' | tr ',' '\n' | grep WATCHTOWER_SCHEDULE

Step 3: Add notifications (email via SMTP or a webhook)

Silent updates are how small issues turn into long outages.

You want a message every time Watchtower tries to update.

Watchtower supports multiple notifiers. Two practical choices:

  • SMTP email (works almost everywhere, good for an ops inbox)
  • Shoutrrr webhooks (Discord/Slack/Telegram/etc.)

Option A: SMTP email notifications (recommended for reliability)

You’ll need an SMTP relay (your provider, a transactional mail service, or your own mail stack).

Configure environment variables like this:

    environment:
      - WATCHTOWER_LABEL_ENABLE=true
      - WATCHTOWER_SCHEDULE=0 20 3 * * *

      - WATCHTOWER_NOTIFICATIONS=email
      - WATCHTOWER_NOTIFICATION_EMAIL_FROM=watchtower@yourdomain.com
      - WATCHTOWER_NOTIFICATION_EMAIL_TO=ops@yourdomain.com
      - WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.yourmailprovider.com
      - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587
      - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER=watchtower@yourdomain.com
      - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=REPLACE_ME
      - WATCHTOWER_NOTIFICATION_EMAIL_DELAY=2

Common mistake: using port 465 without implicit TLS support.

If your provider requires 465, test carefully. Port 587 with STARTTLS is usually the smoother path.

Option B: Shoutrrr notifications (fast setup)

Shoutrrr uses a single URL-like string. Example for Discord:

    environment:
      - WATCHTOWER_NOTIFICATIONS=shoutrrr
      - WATCHTOWER_NOTIFICATION_URL=discord://TOKEN@WEBHOOKID

Use your platform’s exact Shoutrrr format.

Treat the URL like a credential. Don’t commit it to Git.

Apply and test notifications without waiting for the schedule

Run Watchtower once in “check now” mode.

This uses the same image, but runs a one-off container. It lets you validate settings immediately:

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_LABEL_ENABLE=true \
  -e WATCHTOWER_NOTIFICATIONS_LEVEL=debug \
  $(docker inspect --format='{{.Config.Image}}' watchtower) \
  --run-once --debug

Confirm the email or webhook arrives.

If it doesn’t, the debug output usually points to SMTP auth, DNS, or a malformed webhook URL.

Step 4: Pin versions and control risk with tags

Updates get safer when you pin major versions.

The latest tag can jump across breaking changes with no warning.

Rules that hold up in production:

  • Prefer app:1 or app:1.2 over latest
  • Avoid major auto-upgrades for databases and other stateful services
  • Read upstream release notes before changing major tags

Example: instead of traefik/whoami:latest, pin to a stable major or minor if the project offers one.

Verify what you’re currently running

docker images --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.CreatedSince}}'

docker compose config | sed -n '1,140p'

Step 5: Add healthchecks so Watchtower doesn’t “update into downtime”

Watchtower can restart containers.

It can’t tell whether your app is actually working unless you define a healthcheck.

Add a healthcheck wherever it makes sense.

Example healthcheck for a simple HTTP service:

  whoami:
    image: traefik/whoami:latest
    container_name: whoami
    restart: unless-stopped
    ports:
      - "8080:80"
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1/ > /dev/null || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s
    labels:
      - "com.centurylinklabs.watchtower.enable=true"

Verify health status

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

docker inspect whoami --format '{{json .State.Health}}' | head

If a container has no healthcheck, you won’t see (healthy) in docker ps.

Step 6: Reduce blast radius with project separation

If you host multiple apps, avoid one giant Compose file.

Split by “failure domain” so an update or restart doesn’t ripple into unrelated services.

  • /opt/apps/wiki/docker-compose.yml
  • /opt/apps/analytics/docker-compose.yml
  • /opt/apps/proxy/docker-compose.yml
  • /opt/ops/watchtower/docker-compose.yml

Run a single Watchtower instance that can see the Docker daemon (via the socket).

Keep label-only updates across all projects.

Step 7: Implement a rollback plan you can execute in under 2 minutes

Rollback turns “automatic updates” into “controlled updates.”

The goal is simple: revert the image and get the service back up fast.

Rollback method A: redeploy the previous image by ID

After an update, Docker may still have the prior image locally (unless you cleaned it up).

If the app breaks, find the previous image ID and retag it.

# Show image history for a repository
docker images --digests --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.CreatedSince}}' | head -n 20

Then retag a previous image ID to the tag your compose file uses:

# Example: retag previous image ID to current tag
docker tag OLD_IMAGE_ID traefik/whoami:latest

# Restart the service
docker compose up -d whoami

Pitfall: if WATCHTOWER_CLEANUP=true, the old image may be removed.

For critical apps, you may still want cleanup.

Keep rollback predictable by pinning tags (method B).

Rollback method B (recommended): pin a known-good tag in Compose

This is more predictable and easier to audit.

Change the image tag in docker-compose.yml back to the last known-good version, then redeploy.

# Edit the compose file, set a known-good tag, then:
docker compose pull
docker compose up -d

Rollback verification checklist

  • Check container status: docker ps
  • Check health: docker inspect ...
  • Check logs for errors: docker logs --tail=80 service
  • Hit the service endpoint from the VPS: curl -fsS http://127.0.0.1:PORT/

Step 8: Hardening notes (Docker socket, firewall, and least surprise)

Mounting /var/run/docker.sock gives Watchtower root-equivalent control over Docker.

That’s normal for this tool. Treat the container as privileged infrastructure.

  • Keep your VPS patched.
  • Restrict SSH access and use key auth.
  • Don’t expose Docker’s TCP API.
  • Only run trusted images.

Quick firewall sanity check

On Ubuntu/Debian with UFW:

sudo ufw status verbose

At minimum, you usually want 22/tcp (or your SSH port) and 80/443 for web services.

Block everything else unless you have a clear reason to open it.

If you want a baseline, HostMyCode’s guide on setting up Fail2ban for Nginx on Ubuntu VPS pairs well with any public server to cut down brute-force noise.

Step 9: Logging and auditing updates

When something updates, you should be able to answer three questions:

What changed, when it changed, and what restarted.

View Watchtower’s recent activity

docker logs --since=24h watchtower

Check what changed on a specific container

# Container start time (did it restart?)
docker inspect whoami --format 'StartedAt={{.State.StartedAt}} Image={{.Image}}'

# Current image ID in use
docker inspect whoami --format '{{.Image}}'

Disk usage guardrail (don’t let images fill your VPS)

Even with cleanup, logs and volumes tend to grow over time.

Keep an eye on Docker disk usage:

docker system df

If you’re already tight on space, fix that first.

This tutorial walks you through safe cleanup: Disk Full on VPS: Find Large Files and Free Space Safely.

Step 10: Updating responsibly (staging, backups, and databases)

Watchtower updates images. It does not back up your data.

If you run stateful services, you need tested backups and at least one restore drill under your belt.

If your stack includes MySQL/MariaDB, set up a backup job you have actually restored from.

This HostMyCode tutorial covers the full loop: Set Up Automatic MySQL Backups With Tested Restores.

A practical “staging-first” workflow for self-hosters

  • Run a second small VPS as staging, or a second Compose project on the same server using different ports.
  • Enable Watchtower labels on staging first.
  • Let it run for a week. Watch notifications.
  • Only then label-enable production containers.

If you want Git-based deploys with approvals, consider an app PaaS layer.

Keep Watchtower for low-risk services.

HostMyCode has a practical walkthrough for installing Coolify for Git-based deploys.

Common mistakes (and how to spot them fast)

  • Everything updates at once: you forgot WATCHTOWER_LABEL_ENABLE=true or you didn’t add labels to your services.
  • No updates happen: the schedule is wrong (remember Watchtower’s 6-field cron) or your image tag never changes upstream.
  • Updates happen but the app breaks: you used latest and the vendor shipped a breaking change.
  • Notifications never arrive: DNS/firewall blocks SMTP, or webhook URL is malformed. Re-run the --run-once --debug test.
  • Disk fills up: you disabled cleanup, or volumes/logs are growing. Check docker system df and your log retention.

Summary: a production-safe Watchtower Docker Compose setup

The pattern that holds up on a VPS is boring in the best way: label-only updates, scheduled runs, notifications, and pinned versions for anything that matters.

Add healthchecks where you can. Keep a rollback plan you’ve practiced at least once.

If you’d rather spend your time on the application than the host, move the stack to managed VPS hosting or step up to a larger HostMyCode VPS as your container count grows. Predictable resources and predictable ops matter more once updates run on autopilot.

Running several Docker Compose apps on one server is simpler when the underlying infrastructure stays consistent—and help is available when an update goes sideways. HostMyCode’s VPS plans give you full control for self-hosting, while managed VPS hosting shifts routine maintenance and monitoring off your plate.

FAQ: Watchtower auto-updates on a VPS

Can Watchtower update only one Compose project?

Yes. The safest approach is label-based updates.

Add com.centurylinklabs.watchtower.enable=true only to the services you want updated, regardless of which Compose project they live in.

Should I let Watchtower update databases like PostgreSQL or MariaDB?

Not automatically across major versions.

If you keep a pinned major tag (for example postgres:16) and you have tested backups and restores, minor updates can be reasonable. Treat any major bump as a planned maintenance change.

How do I stop Watchtower from touching a critical service?

Remove the Watchtower enable label from that service (or set it to false).

With WATCHTOWER_LABEL_ENABLE=true, unlabeled services are ignored.

What’s the fastest way to verify an update didn’t break production?

Check docker ps for restarts.

Confirm (healthy) status for services with healthchecks, and run a local curl from the VPS to the backend port. Then check your public URL through the reverse proxy.

Is it OK to run Watchtower on shared hosting?

No. Watchtower needs Docker access, which isn’t available on typical shared hosting. Use a VPS or dedicated server for container workloads.