Updating a Docker Compose stack in production

Why `latest` is the real culprit

What this guide covers — and what it does not

• What this guide covers: a step-by-step protocol to update a Docker Compose stack on a VPS — version pinning, volume backup, release notes review, fast rollback, healthchecks as a safety net.
• Covered elsewhere: the initial hardening checklist (docker-compose-production-checklist), configuring depends_on and service_healthy (docker-compose-depends-on-healthcheck), and comparing auto-update tools like Watchtower or Diun.
• What this guide does not recommend: Watchtower or any auto-pull tool in production — that is precisely the anti-pattern the breaking change cases illustrate.
• Target audience: developers and agencies managing one or more Docker Compose stacks in production on a VPS, with root access and persistent volumes.

Step 1 — Pin all your images

docker inspect --format='{{index .RepoDigests 0}}' getmeili/meilisearch:v1.53.0

Update protocol — the 5 steps

1. 01

   Read the release notes before pulling

   First, check the release notes for the new version. Look for the words breaking, migration, incompatible, pg_upgrade, dump. This is not optional: Supabase explicitly documented that upgrading from PostgreSQL 15 to 17 requires a manual pg_upgrade — the PG 17 container refuses to start on a PG 15 volume, and the initialization process does not automatically migrate data.

   For Langfuse v4 (released August 17, 2026), Python SDK v2 and older are rejected at ingestion by the new stack — a breaking change that affects all client services tracing via the old API.

   Three minutes of reading saves several hours of data recovery.

2. 02

   Back up volumes before pulling

   Never pull before having a usable backup. For named volumes, two approaches:

   Application dump (recommended for databases) — the service must be healthy before dumping:

   docker compose exec db pg_dump -U postgres -Fc mydb > backup_$(date +%Y%m%d_%H%M%S).dump

   Raw volume snapshot — useful for binary stores (Meilisearch, Redis, MinIO):

   docker run --rm \
     --volumes-from $(docker compose ps -q meilisearch) \
     -v $(pwd)/backups:/backup \
     alpine tar czf /backup/meili_$(date +%Y%m%d_%H%M%S).tar.gz /meili_data

   Verify the backup is readable before proceeding. A corrupt dump file discovered during recovery is the most expensive scenario there is.

3. 03

   Pull the new image and test offline

   Update the tag in your docker-compose.yml, then pull the image without restarting the service:

   docker compose pull meilisearch

   If your environment allows it, test the new image on a volume clone in a ddev environment or a staging VM before touching production. Check the startup logs for any migration errors:

   docker compose up -d meilisearch
   docker compose logs -f meilisearch

   Wait for the healthcheck to reach healthy before validating. A service that starts but is not yet healthy is not a ready service.

4. 04

   Check healthchecks

   A well-configured healthcheck is your first detection line. It must be present on every critical service in the stack, in Compose v2 format:

   healthcheck:
     test: ["CMD-SHELL", "curl -sf http://localhost:7700/health || exit 1"]
     interval: 10s
     timeout: 5s
     retries: 5
     start_period: 30s

   The start_period field is critical for slow-starting services (databases, search engines): it prevents Docker from declaring the container unhealthy during the initialization phase and triggering a premature restart.

   See docker-compose-depends-on-healthcheck for the full service_healthy configuration on PostgreSQL — the same principle applies to any service that needs a warm-up period.

5. 05

   Roll back if something breaks

   If the new version fails to start or produces errors, rollback must take under two minutes. The procedure:

   1. Revert to the previous tag in docker-compose.yml (or git revert if you committed the bump).
   2. Restart only the affected service, without recreating volumes:

   docker compose up -d --no-deps --force-recreate meilisearch

   3. Check the logs immediately:

   docker compose logs -f meilisearch

   The --no-deps flag is essential: it restarts the target service without touching other containers (database, cache, proxy). Without it, docker compose up -d may recreate the entire stack.

   ⚠️ If the new version migrated the on-disk data format (Meilisearch v1.54, Supabase PG17), rolling back the image is not enough — which is why the volume backup is a precondition, not an option.

Recent breaking changes that took down instances

Update strategies: comparison

Scroll the table

Integrating this protocol into your workflow

# .env
MEILISEARCH_VERSION=v1.53.0
POSTGRES_VERSION=15.6

# docker-compose.yml
services:
  meilisearch:
    image: getmeili/meilisearch:${MEILISEARCH_VERSION}