Actualizar un stack Docker Compose en producción

Por qué `latest` es el verdadero culpable

Qué cubre esta guía — y qué no

• Qué cubre esta guía: el protocolo paso a paso para actualizar un stack Docker Compose en un VPS — version pinning, backup de volúmenes, revisión de notas de versión, rollback rápido, healthchecks como red de seguridad.
• Cubierto en otras guías: el checklist de hardening inicial (docker-compose-production-checklist), la configuración de depends_on y service_healthy (docker-compose-depends-on-healthcheck), y la comparativa de herramientas de actualización automática como Watchtower o Diun.
• Lo que esta guía no recomienda: Watchtower o cualquier herramienta de auto-pull en producción — ese es precisamente el antipatrón que ilustran los casos de breaking changes.
• Público objetivo: desarrolladores y agencias que gestionan uno o más stacks Docker Compose en producción en un VPS, con acceso root y volúmenes persistentes.

Paso 1 — Fija todas tus imágenes

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

Protocolo de actualización — los 5 pasos

1. 01

   Lee las notas de versión antes de hacer pull

   Primero, consulta las notas de versión de la nueva versión. Busca las palabras breaking, migration, incompatible, pg_upgrade, dump. Esto no es opcional: Supabase documentó explícitamente que actualizar de PostgreSQL 15 a 17 requiere un pg_upgrade manual — el contenedor PG 17 se niega a arrancar sobre un volumen PG 15, y el proceso de inicialización no migra los datos automáticamente.

   Para Langfuse v4 (lanzado el 17 de agosto de 2026), los SDKs Python v2 y anteriores son rechazados en la ingesta por el nuevo stack — un cambio disruptivo que afecta a todos los servicios cliente que rastrean mediante la API antigua.

   Tres minutos de lectura te ahorran varias horas de recuperación de datos.

2. 02

   Haz backup de los volúmenes antes del pull

   Nunca hagas pull sin tener un backup utilizable. Para volúmenes nombrados, dos enfoques:

   Dump aplicativo (recomendado para bases de datos) — el servicio debe estar healthy antes de hacer el dump:

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

   Snapshot de volumen en crudo — útil para almacenes binarios (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

   Verifica que el backup es legible antes de continuar. Un archivo de dump corrupto descubierto durante la recuperación es el escenario más costoso que existe.

3. 03

   Descarga la nueva imagen y pruébala fuera de producción

   Actualiza el tag en tu docker-compose.yml, luego descarga la imagen sin reiniciar el servicio:

   docker compose pull meilisearch

   Si tu entorno lo permite, prueba la nueva imagen sobre un clon del volumen en un entorno ddev o una VM de staging antes de tocar producción. Revisa los logs de arranque en busca de errores de migración:

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

   Espera a que el healthcheck alcance el estado healthy antes de validar. Un servicio que arranca pero no está healthy todavía no es un servicio listo.

4. 04

   Verifica los healthchecks

   Un healthcheck bien configurado es tu primera línea de detección. Debe estar presente en cada servicio crítico del stack, en formato Compose v2:

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

   El campo start_period es crítico para servicios de arranque lento (bases de datos, motores de búsqueda): evita que Docker declare el contenedor unhealthy durante la fase de inicialización y desencadene un reinicio prematuro.

   Consulta docker-compose-depends-on-healthcheck para la configuración completa de service_healthy en PostgreSQL — el mismo principio aplica a cualquier servicio que necesite un período de calentamiento.

5. 05

   Rollback si algo falla

   Si la nueva versión no arranca o produce errores, el rollback debe tomar menos de dos minutos. El procedimiento:

   1. Vuelve al tag anterior en docker-compose.yml (o git revert si hiciste commit del bump).
   2. Reinicia únicamente el servicio afectado, sin recrear los volúmenes:

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

   3. Revisa los logs inmediatamente:

   docker compose logs -f meilisearch

   El flag --no-deps es esencial: reinicia el servicio objetivo sin tocar los otros contenedores (base de datos, caché, proxy). Sin él, docker compose up -d puede recrear todo el stack.

   ⚠️ Si la nueva versión migró el formato de los datos en disco (Meilisearch v1.54, Supabase PG17), revertir la imagen no es suficiente — por eso el backup del volumen es una precondición, no una opción.

Los breaking changes recientes que derribaron instancias

Estrategias de actualización: comparativa

Desplace la tabla

Integrar este protocolo en tu flujo de trabajo

# .env
MEILISEARCH_VERSION=v1.53.0
POSTGRES_VERSION=15.6

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