Docker Compose en producción: checklist de 10 puntos

Docker Compose se diseñó para el desarrollo: sus valores por defecto priorizan la simplicidad, no la robustez. Un contenedor no se reinicia tras un reinicio del host, sus logs crecen sin límite, puede consumir toda la RAM de la máquina y escucha en todas las interfaces de red. En desarrollo, ninguno de estos comportamientos supone un problema. En producción, esos ajustes ausentes se convierten en incidentes: disco lleno a las tres de la madrugada, base de datos perdida tras un docker compose down, servicio inaccesible tras un corte de corriente. La buena noticia: endurecer una stack Compose no exige reescribirla, solo una decena de añadidos concretos. Repase cada punto antes de publicar y su servicio aguantará la carga y los reinicios sin vigilancia constante.

Necesita un VPS con Docker Engine y el plugin Compose v2. El comando es docker compose, sin guion: compruébelo con docker compose version, porque la sintaxis deploy.resources fuera de Swarm exige Compose v2 (el antiguo docker-compose se trata más abajo). Controle también el motor con docker version. Docker Engine 29.7.2 corrige CVE-2026-17106 (CopyEscape), una race condition de docker cp divulgada el 10 de agosto de 2026: un contenedor no fiable puede sobrescribir con ella un archivo del host, incluido el binario runc. En los equipos de trabajo, el parche llegó con Docker Desktop 4.86.0. Mientras no actualice, no ejecute docker cp desde un contenedor cuyo contenido no controla. Guarde el proyecto en una carpeta dedicada (/opt/miapp), con un .env en chmod 600. Prevea un proxy inverso delante — Traefik, Caddy o Nginx —, porque el binding de puertos supone que el tráfico público nunca llega a sus contenedores, y versione el archivo Compose.

Dos herramientas llevan casi el mismo nombre. docker-compose, con guion, es Compose v1, escrito en Python: su repositorio lo declara al final de su vida útil desde la disponibilidad general de Compose v2, anunciada por Docker el 26 de abril de 2022. docker compose, con un espacio, es Compose v2, escrito en Go e integrado en la CLI de Docker como plugin. Ubuntu 26.04 completa la transición: el paquete docker-compose ya no está en el archivo desde Ubuntu 25.10, y el paquete docker-compose-v2 solo instala el plugin, en /usr/libexec/docker/cli-plugins/. Tras la actualización, cualquier script que siga llamando al nombre antiguo se detiene en docker-compose: command not found. En la CI, GitHub sacó Compose v1 de sus runners alojados el 9 de julio de 2024, y pasa ubuntu-latest a Ubuntu 26.04 entre el 19 de octubre y el 19 de noviembre de 2026: conviene revisar un workflow que instalaba docker-compose a mano. Hay dos diferencias de comportamiento documentadas. Los nombres de contenedor usan un guion en lugar de un guion bajo (miapp-web-1 frente a miapp_web_1), salvo con --compatibility. Y la clave version: se ignora, con la advertencia «the attribute version is obsolete, it will be ignored».

Un health check bien configurado va más allá de un simple curl: mide el estado funcional del servicio, no solo su disponibilidad de red. Para una API HTTP, pruebe un endpoint ligero (/health o /ready) que devuelva 200 solo si la conexión a la base de datos está establecida. Para PostgreSQL, use pg_isready -U postgres. Para Redis, basta con redis-cli ping. Compruebe el estado de sus contenedores con docker compose ps: la columna STATUS muestra healthy, unhealthy o starting. Un contenedor atascado en starting más allá del start_period indica un problema de inicialización — consulte docker compose logs service. El parámetro start_period define una ventana de gracia durante la cual los fallos no cuentan en los retries, imprescindible para servicios que necesitan tiempo para migrar su esquema.

Fuera de Swarm, Compose acepta secretos de tipo archivo. Declare el secreto en la sección secrets: de nivel raíz, apuntando a un archivo local (file: ./secrets/db_password.txt), y referéncielo en el servicio con secrets: [db_password]. Docker monta ese archivo en solo lectura en /run/secrets/db_password: la aplicación lo lee como un archivo normal, y su valor no aparece ni en las variables de entorno que muestra docker inspect ni en los logs. Para rotarlo, versione el secreto: cree db_password_v2 junto a db_password_v1, haga que el servicio lea v2, redespliéguelo solo con docker compose up -d --no-deps service y elimine v1 una vez validado el despliegue. La interrupción se limita a recrear ese contenedor, y el secreto anterior sigue disponible para volver atrás.

El rollback de una stack Compose se prepara antes del despliegue, no después del incidente. Mantenga la imagen anterior etiquetada y disponible en local: añada un tag explícito miapp:stable antes de cada actualización. Para volver atrás, restablezca el tag anterior en el archivo Compose (o en el .env si la versión es una variable) y relance docker compose up -d. Los volúmenes no se ven afectados por un cambio de imagen, lo que hace rápido el rollback aplicativo; una migración de esquema, en cambio, necesita su migración inversa lista antes del despliegue. Para publicaciones críticas, separe docker-compose.yml (versión estable) y docker-compose.override.yml (versión candidata): docker compose -f docker-compose.yml up -d ignora el override y vuelve al estado estable.

docker: unknown command: docker compose: el plugin Compose no está instalado. En Ubuntu, instale docker-compose-v2 desde el archivo, o docker-compose-plugin si Docker viene del repositorio oficial de Docker, y compruebe con docker compose version. network not found: tras un docker compose down, las redes con nombre se eliminan. Solución: declare las redes compartidas como external: true o sincronice el reinicio de las stacks dependientes. port is already in use: otro proceso ocupa el puerto. Identifíquelo con ss -tlnp | grep :PORT y deténgalo antes de relanzar. OOM (Out Of Memory): el kernel mata un contenedor sin aviso — busque OOMKilled: true en docker inspect container_id. Aumente el límite de memoria o identifique la fuga con docker stats. permission denied on volume: el proceso del contenedor corre con un UID sin acceso al directorio montado. Compruebe el UID con docker compose exec service id y ajuste los permisos o añada user: "UID:GID". Contenedor reiniciándose en bucle: docker compose logs --tail=50 service revela el error de arranque. Causas más frecuentes: variable de entorno ausente, archivo de configuración no encontrado o dependencia no lista.

Copiar archivos de un volumen PostgreSQL o MySQL en caliente con rsync o tar produce casi siempre una copia corrupta. La regla es hacer siempre un dump SQL antes del snapshot del volumen: pg_dump o mysqldump producen un estado coherente. Herramientas como Restic y Offen Docker Backup automatizan este proceso. Documente cada volumen con nombre y asócielo a una estrategia de restauración probada.

Estos diez ajustes transforman un archivo Compose de desarrollo en una stack capaz de sobrevivir a reinicios, picos de carga y noches sin supervisión. Los health checks, los secretos montados como archivo, un rollback preparado y el paso completo a docker compose completan esta base. Nada de esto requiere una herramienta adicional: todo cabe en el YAML y los scripts que ya tiene. Repase la checklist antes de cada publicación, por ejemplo con una revisión de docker compose config integrada en el despliegue. Después podrá añadir un proxy inverso como Traefik o Caddy, o una capa de orquestación como Coolify.