Cómo funciona Docker Compose

Lección 7 del curso de Docker.

Cómo funciona Docker Compose

Las aplicaciones reales rara vez son un solo contenedor: suelen combinar una aplicación, una base de datos, una caché... Arrancar cada pieza a mano con docker run es tedioso y propenso a errores. Docker Compose resuelve esto: describes toda la aplicación en un solo archivo YAML y la levantas entera con un único comando.

El archivo docker-compose.yml

Compose se define en un archivo llamado docker-compose.yml (o compose.yaml) en la raíz del proyecto. En él declaras los servicios (los contenedores), las redes y los volúmenes que necesitan:

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
    volumes:
      - ./web:/usr/share/nginx/html
    depends_on:
      - db

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: curso
      POSTGRES_PASSWORD: secreto
      POSTGRES_DB: aplicacion
    volumes:
      - datos-db:/var/lib/postgresql/data

volumes:
  datos-db:

Qué hace Compose por ti

Crea automáticamente una red dedicada para el proyecto, donde los servicios se resuelven entre sí por su nombre (la aplicación puede conectar a la base de datos usando simplemente db como host).
Arranca los servicios en el orden correcto respetando depends_on.
Gestiona los volúmenes y la configuración declarada, y recrea solo lo que ha cambiado.

Comandos esenciales

Todos se ejecutan en la carpeta donde está el docker-compose.yml:

docker compose up -d        # crea y arranca toda la aplicación en segundo plano
docker compose ps           # estado de los servicios
docker compose logs -f web  # logs de un servicio en tiempo real
docker compose exec web bash  # shell dentro de un servicio
docker compose build        # reconstruye las imágenes que usan Dockerfile
docker compose up -d --build  # reconstruye y reinicia lo necesario
docker compose stop         # detiene los servicios sin borrarlos
docker compose down         # detiene y elimina contenedores y red
docker compose down -v      # además borra los volúmenes (¡pierdes los datos!)

Variables de entorno

Para no escribir contraseñas en el YAML, Compose lee automáticamente un archivo .env en la misma carpeta:

# archivo .env
POSTGRES_PASSWORD=secreto

# en docker-compose.yml
environment:
  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

Cuándo usarlo

Compose es la herramienta estándar para entornos de desarrollo, pruebas y despliegues sencillos en uno o pocos servidores. Cuando la aplicación crece hasta necesitar varios servidores, escalado automático o alta disponibilidad, el paso natural es un orquestador como Kubernetes (lección 3).

Errores frecuentes al empezar con Compose

El error más habitual es la indentación: el YAML solo admite espacios, nunca tabuladores, y un nivel mal alineado cambia el significado del archivo. Si Compose se queja al arrancar, ejecuta docker compose config para validar el archivo y ver cómo lo interpreta antes de levantar nada.

Otro fallo común es confundir depends_on con esperar a que un servicio esté listo. Esa opción controla el orden de arranque, pero no garantiza que la base de datos ya acepte conexiones. Para aplicaciones delicadas puedes añadir un healthcheck al servicio y hacer que el otro espere a que esté sano.

También conviene no subir el archivo .env a un repositorio público, porque contiene contraseñas. Añádelo a .gitignore y deja un .env.example con los nombres de las variables pero sin los valores reales. Por último, recuerda que docker compose down -v borra los volúmenes: úsalo solo cuando quieras empezar de cero y tengas copia de lo importante.

Si trabajas con varios proyectos, ponle a cada uno su propia carpeta y su propio archivo, de modo que los nombres de servicios, redes y volúmenes no se mezclen entre ellos. Compose usa el nombre de la carpeta como prefijo, lo que ayuda a distinguirlos.

Compose en el día a día

Una vez que tienes el archivo docker-compose.yml escrito, el trabajo diario se reduce a tres gestos. Por la mañana levantas el entorno con un solo comando y todos los servicios arrancan en el orden correcto, con su red y sus volúmenes ya conectados. Durante el día consultas los registros de todos los contenedores a la vez, sin tener que recordar el nombre de cada uno. Y al terminar, otro comando lo apaga todo de forma ordenada, sin dejar contenedores sueltos consumiendo memoria.

Esa sencillez es la razón por la que Compose se ha convertido en la forma habitual de trabajar en local. El archivo queda guardado junto al código del proyecto, así que cualquier persona del equipo puede levantar el mismo entorno en su máquina en cuestión de segundos, sin instrucciones largas ni pasos manuales que se olvidan con facilidad.

Buscar este blog

Curso Docker