Docker Compose Watch

docker compose watch

Docker Compose Watch es una característica que permite acelerar significativamente el flujo de desarrollo mediante la detección automática de cambios en archivos del proyecto y la aplicación de actualizaciones en tiempo real sin necesidad de reconstruir o reiniciar manualmente los contenedores.

Esta funcionalidad transforma el ciclo tradicional de desarrollo donde cada cambio requería detener el servicio, reconstruir la imagen y volver a iniciar el contenedor, convirtiéndolo en un proceso continuo y automático.

Funcionamiento básico

El comando docker compose watch inicia un proceso que monitoriza los archivos especificados en la configuración de cada servicio y ejecuta acciones predefinidas cuando detecta modificaciones.

docker compose watch

Una vez ejecutado, el comando permanece activo y muestra en tiempo real los cambios detectados y las acciones realizadas, proporcionando feedback inmediato sobre el estado de sincronización.

Configuración en compose.yaml

Para habilitar el watch en un servicio, se debe agregar la sección develop con la configuración watch dentro de la definición del servicio:

services:
  app:
    build: .
    ports:
      - "3000:3000"
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
        - action: rebuild
          path: ./package.json

La configuración watch acepta una lista de reglas que definen qué archivos monitorizar y qué acción ejecutar cuando cambian.

Tipos de acciones

Docker Compose Watch soporta dos tipos principales de acciones que determinan cómo se manejan los cambios detectados:

1. Acción sync

La acción sync copia los archivos modificados directamente al contenedor sin reiniciarlo ni reconstruir la imagen. Es la opción más rápida y se utiliza para archivos que no requieren recompilación.

- action: sync
  path: ./src
  target: /app/src
  ignore:
    - "*.log"
    - "node_modules/"

2. Acción rebuild

La acción rebuild reconstruye completamente la imagen cuando se detectan cambios en archivos críticos como dependencias o configuración del build.

- action: rebuild
  path: ./package.json

Patrones de exclusión

El sistema permite definir patrones de archivos a ignorar mediante la propiedad ignore, evitando sincronizaciones innecesarias de archivos temporales o generados automáticamente.

develop:
  watch:
    - action: sync
      path: ./src
      target: /app/src
      ignore:
        - "**/*.tmp"
        - "**/*.log"
        - "**/node_modules/**"
        - "**/.git/**"

Los patrones siguen la sintaxis de glob estándar, permitiendo exclusiones específicas y eficientes.

Ejemplo práctico con Node.js

Un caso común de uso es una aplicación Node.js donde queremos sincronizar cambios en código fuente pero reconstruir cuando se modifican las dependencias:

services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
    develop:
      watch:
        # Sincronizar código fuente
        - action: sync
          path: ./src
          target: /app/src
        # Sincronizar archivos estáticos
        - action: sync
          path: ./public
          target: /app/public
        # Reconstruir si cambian las dependencias
        - action: rebuild
          path: ./package.json
        - action: rebuild
          path: ./package-lock.json

Detección de cambios

El sistema de detección utiliza eventos del sistema de archivos del sistema operativo para identificar modificaciones, creaciones y eliminaciones de archivos de forma eficiente y con baja latencia.

Los cambios se detectan recursivamente en todos los subdirectorios de las rutas especificadas, respetando siempre los patrones de exclusión configurados.

Integración con hot reload

Docker Compose Watch funciona especialmente bien con aplicaciones que implementan hot reload interno, como servidores de desarrollo de frameworks web modernos:

services:
  frontend:
    build: 
      context: .
      target: development
    ports:
      - "5173:5173"
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
        - action: sync
          path: ./index.html
          target: /app/index.html
        - action: rebuild
          path: ./vite.config.js

En este ejemplo, los cambios en archivos fuente se sincronizan inmediatamente, mientras que las modificaciones en la configuración de Vite provocan una reconstrucción completa.

Comandos útiles

Iniciar watch en modo detached:

docker compose watch --detach

Ver logs durante el watch:

docker compose watch --no-up

Combinar con up para inicio completo:

docker compose up --watch

Este último comando inicia los servicios y activa automáticamente el modo watch, combinando ambas operaciones en una sola instrucción.

Flujo dev con hot reload

El flujo de desarrollo con hot reload mediante Docker Compose Watch establece un entorno donde los cambios en el código se reflejan instantáneamente en la aplicación en ejecución, eliminando la fricción tradicional del desarrollo con contenedores.

Configuración del entorno de desarrollo

Para implementar un flujo eficiente de hot reload, es fundamental configurar correctamente tanto el contenedor como la aplicación para trabajar en modo desarrollo:

services:
  api:
    build:
      context: .
      target: development  # Stage específico para desarrollo
    ports:
      - "8000:8000"
    environment:
      - NODE_ENV=development
      - CHOKIDAR_USEPOLLING=true  # Para sistemas de archivos montados
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
        - action: sync
          path: ./routes
          target: /app/routes
        - action: rebuild
          path: ./package.json

La variable CHOKIDAR_USEPOLLING=true es especialmente importante cuando se trabaja con sistemas de archivos montados entre host y contenedor, ya que mejora la detección de cambios.

Configuración específica por tecnología

Node.js con Nodemon:

services:
  node-app:
    build: .
    ports:
      - "3000:3000"
    command: ["npm", "run", "dev"]  # Usa nodemon internamente
    environment:
      - NODE_ENV=development
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
        - action: sync
          path: ./public
          target: /app/public
          ignore:
            - "**/*.log"

Python con Flask en modo debug:

services:
  flask-app:
    build: .
    ports:
      - "5000:5000"
    environment:
      - FLASK_ENV=development
      - FLASK_DEBUG=1
    develop:
      watch:
        - action: sync
          path: ./app
          target: /app/app
        - action: rebuild
          path: ./requirements.txt

Go con Air para hot reload:

services:
  go-app:
    build:
      context: .
      target: development
    ports:
      - "8080:8080"
    command: ["air", "-c", ".air.toml"]
    develop:
      watch:
        - action: sync
          path: ./cmd
          target: /app/cmd
        - action: sync
          path: ./internal
          target: /app/internal
        - action: rebuild
          path: ./go.mod
        - action: rebuild
          path: ./go.sum

Optimización del flujo de sincronización

Para maximizar la velocidad del hot reload, es crucial entender qué archivos requieren sincronización versus reconstrucción completa:

develop:
  watch:
    # Archivos que solo requieren copia (más rápido)
    - action: sync
      path: ./src/components
      target: /app/src/components
    - action: sync
      path: ./src/utils
      target: /app/src/utils
    
    # Archivos que requieren restart del proceso
    - action: sync+restart
      path: ./src/config
      target: /app/src/config
    
    # Archivos que requieren rebuild completo
    - action: rebuild
      path: ./Dockerfile
    - action: rebuild
      path: ./package.json

Configuración de exclusiones inteligentes

Un aspecto crítico del flujo es excluir archivos que no afectan la funcionalidad pero que cambian frecuentemente:

develop:
  watch:
    - action: sync
      path: ./src
      target: /app/src
      ignore:
        - "**/*.test.js"      # Tests unitarios
        - "**/*.spec.js"      # Especificaciones
        - "**/coverage/**"    # Reportes de cobertura
        - "**/.DS_Store"      # Archivos del sistema
        - "**/logs/**"        # Archivos de log
        - "**/dist/**"        # Archivos compilados

Configuración multi-servicio

En aplicaciones full-stack con múltiples servicios, cada uno requiere su propia configuración de hot reload:

services:
  frontend:
    build:
      context: ./frontend
      target: development
    ports:
      - "3000:3000"
    develop:
      watch:
        - action: sync
          path: ./frontend/src
          target: /app/src
        - action: rebuild
          path: ./frontend/package.json
  
  backend:
    build:
      context: ./backend
      target: development
    ports:
      - "8000:8000"
    develop:
      watch:
        - action: sync
          path: ./backend/app
          target: /app/app
        - action: rebuild
          path: ./backend/requirements.txt
  
  database:
    image: postgresql:16
    # Sin watch - no requiere hot reload

Flujo de trabajo típico

El flujo de desarrollo estándar con hot reload sigue estos pasos:

• 1. Inicio del entorno:

docker compose up --build --watch

• 2. Desarrollo activo: Los cambios en archivos fuente se sincronizan automáticamente y la aplicación se recarga sin intervención manual

• 3. Cambios en dependencias: Cuando se modifican archivos como package.json o requirements.txt, se ejecuta automáticamente un rebuild

• 4. Monitoreo en tiempo real: El terminal muestra el estado de sincronización y los logs de la aplicación simultáneamente

Debugging y troubleshooting

Para diagnosticar problemas en el hot reload, es útil activar el modo verbose:

docker compose watch --verbose

Esto proporciona información detallada sobre qué archivos se están monitorizando y qué acciones se ejecutan en cada cambio.

Consideraciones de rendimiento

El hot reload funciona mejor cuando se limita el alcance de monitorización:

develop:
  watch:
    # Específico - mejor rendimiento
    - action: sync
      path: ./src/pages
      target: /app/src/pages
    
    # Evitar rutas muy amplias que incluyan muchos archivos
    # - action: sync
    #   path: ./
    #   target: /app/

La configuración granular reduce la carga del sistema de archivos y mejora los tiempos de respuesta del hot reload.