Docker Compose para el desarrollo local: archivos override, perfiles, dependencias saludables y watch

Objetivo

Lograr un único docker compose up que entregue a cada contribuyente la misma base de datos, la misma cola y las mismas versiones de servicio que en producción, con recarga rápida de código, sin convertir el archivo confirmado en un artefacto solo local.

Requisitos previos

Un Dockerfile por servicio que construya desde un checkout limpio, comprobaciones de salud definidas para las dependencias con estado, y configuración leída desde variables de entorno.

Pasos

1. Escribir compose.yaml como la base con la forma de producción: imágenes por etiqueta, nombres de servicio que coincidan con los nombres DNS usados en la configuración, sin puertos de host, sin bind mounts. La documentación de Docker (citada) indica que Compose lee compose.yaml y, opcionalmente, compose.override.yaml por defecto, y los combina, de modo que los archivos posteriores sobrescriben o extienden a los anteriores.
2. Colocar las comodidades locales en compose.override.yaml: puertos publicados, un bind mount del árbol de código fuente, variables de entorno de depuración. Confirmarlo en el control de versiones si todos los desarrolladores quieren lo mismo; en caso contrario, confirmar un .example e ignorar el real.
3. Declarar las dependencias con condiciones: depends_on: {db: {condition: service_healthy}} hace que Compose espere a la comprobación de salud de la dependencia en lugar de simplemente a que arranque su contenedor; service_completed_successfully espera a que un contenedor de migración de un solo uso termine con código 0 (ambas en la referencia de servicios citada).
4. Asociar las herramientas opcionales (captador de correo, interfaz de administración, generador de carga) a profiles: para que un up simple las omita; iniciarlas con --profile debug o COMPOSE_PROFILES.
5. Añadir una sección develop.watch: sync para código interpretado, sync+restart cuando el proceso debe reiniciarse para recoger los cambios, rebuild cuando cambian los manifiestos de dependencias; ejecutar con docker compose up --watch, o docker compose watch para mantener los eventos de sincronización fuera de los registros de la aplicación. La página de Compose Watch citada documenta estas acciones y señala que watch solo rastrea los servicios construidos desde fuente local con build, no los que usan una image ya construida.
6. Almacenar los valores predeterminados no secretos en .env para la interpolación de variables, y mantener las credenciales fuera de los archivos confirmados; pasarlas mediante entradas env_file que estén excluidas por git-ignore.
7. Ejecutar docker compose config en CI para renderizar el archivo combinado y detectar errores de ruta o de interpolación.

Resultado esperado

Los nuevos contribuyentes llegan a una pila funcional con un solo comando; el archivo base sirve también como documentación de la topología en tiempo de ejecución; las diferencias con producción son visibles como un pequeño archivo override en lugar de ediciones dispersas.

Límites y base de verificación

Compose describe un único host y no es un orquestador de producción; los límites de recursos, las políticas de reinicio y las redes difieren de los de Kubernetes. La página de Compose Watch citada presenta watch como complemento de los bind mounts, no como reemplazo: sus reglas ignore permiten que un árbol como node_modules/ quede fuera de la sincronización, lo cual la página justifica por la carga de E/S de muchos archivos pequeños y por los artefactos compilados que no pueden compartirse entre las plataformas del host y del contenedor. El comportamiento sigue las referencias citadas; no se reivindica ninguna medición de tiempos.