Ya sabes describir una aplicación multi-contenedor en un archivo docker-compose.yml. Ahora toca aprender a operarla: arrancarla, detenerla, inspeccionar su estado, leer sus registros y entrar dentro de sus contenedores para depurar. Docker Compose ofrece un conjunto compacto de comandos que cubren todo el ciclo de vida de una aplicación. En esta lección los recorreremos uno a uno con ejemplos prácticos, presentaremos una tabla resumen para que la tengas siempre a mano y mostraremos el ciclo de trabajo típico que seguirás en tu día a día como desarrollador.

• Dominar los comandos esenciales: up, down, ps, logs, exec, build, stop/start y restart.
• Entender la diferencia entre arrancar en primer plano y en segundo plano (-d).
• Saber distinguir entre down (eliminar) y stop (solo detener).
• Inspeccionar el estado y los registros de tus servicios.
• Interiorizar un ciclo de trabajo eficaz con Compose.

Nota: todos los comandos se ejecutan desde la carpeta donde está tu docker-compose.yml, ya que Compose lo busca en el directorio actual.

docker compose up es el comando central. Lee el archivo, crea las redes y volúmenes necesarios, construye o descarga las imágenes y arranca todos los servicios.

• Arranca todo en primer plano: la terminal queda ocupada mostrando los registros combinados de todos los servicios. Para detenerlo, pulsa Ctrl+C.

Lo más habitual es usar el modo detached (segundo plano):

• -d (detached): arranca los servicios en segundo plano y te devuelve el control de la terminal. La aplicación sigue corriendo aunque cierres la ventana.

Si has cambiado el código y quieres forzar la reconstrucción de las imágenes antes de arrancar:

• --build: reconstruye las imágenes de los servicios que usan build antes de levantar los contenedores. Imprescindible tras modificar tu Dockerfile o tu código.

docker compose down es la operación inversa a up: detiene y elimina los contenedores y la red por defecto creados por Compose.

• Para y borra los contenedores y la red asociada.
• Por defecto conserva los volúmenes con nombre, de modo que tus datos persistentes no se pierden.

Si además quieres eliminar los volúmenes (¡cuidado, borra los datos!):

• -v: elimina también los volúmenes con nombre declarados en el archivo. Úsalo solo cuando quieras empezar de cero, porque destruye los datos.

down vs stop: down elimina contenedores y red (deja de existir); stop solo los detiene (siguen existiendo y se pueden reiniciar con start). Veremos stop/start más adelante.

docker compose ps muestra el estado de los servicios de la aplicación actual.

• Lista cada contenedor con su nombre, la imagen, el estado (running, exited, etc.) y los puertos publicados.
• Solo muestra los contenedores definidos en el docker-compose.yml del directorio actual, lo que lo hace más claro que docker ps.

Para ver también los contenedores detenidos, añade -a:

docker compose logs muestra la salida (registros) de los servicios, muy útil para depurar.

• Imprime los registros combinados de todos los servicios.

Para seguir los registros en tiempo real, como un tail continuo:

• -f (follow): mantiene la salida abierta y muestra los nuevos registros según se producen. Detén con Ctrl+C.

Puedes filtrar por un servicio concreto indicando su nombre:

• Muestra solo los registros del servicio web, en tiempo real.

docker compose exec ejecuta un comando dentro de un contenedor que ya está en marcha. Es la forma estándar de depurar y de abrir una shell interactiva.

Explicación:

• web: el nombre del servicio en cuyo contenedor quieres entrar.
• sh: el comando a ejecutar. Aquí abrimos una shell, lo que te da una terminal dentro del contenedor.
• Algunas imágenes incluyen bash en lugar de sh; en ese caso usa docker compose exec web bash.

También puedes ejecutar comandos puntuales sin abrir una shell interactiva:

• Entra directamente al cliente psql de PostgreSQL dentro del servicio db, conectando con el usuario y la base de datos indicados.

docker compose build construye (o reconstruye) las imágenes de los servicios que tienen la clave build, sin arrancarlos.

• Construye todas las imágenes definidas con build.
• Útil cuando quieres preparar las imágenes por separado del arranque.

Para forzar una reconstrucción completa ignorando la caché:

• --no-cache: reconstruye desde cero sin usar las capas cacheadas. Útil cuando sospechas que la caché está dándote una versión antigua.

A diferencia de down, estos comandos no eliminan los contenedores, solo cambian su estado de ejecución.

Explicación:

• stop: detiene los contenedores pero los conserva. Es como apagar sin desinstalar. Más rápido que down si solo quieres pausar.
• start: vuelve a poner en marcha los contenedores que detuviste con stop. No sirve para contenedores que ya no existen (para eso usa up).
• restart: equivale a un stop seguido de un start. Muy práctico para aplicar cambios de configuración sin recrear nada.

Todos admiten el nombre de un servicio para actuar solo sobre él:

• Reinicia únicamente el servicio web, dejando el resto intacto.

En el día a día, un flujo habitual con Compose se parece a este:

Resumen del flujo:

• Arrancas con up -d y verificas con ps.
• Diagnosticas con logs -f y exec.
• Iteras sobre tu código con up -d --build.
• Pausas con stop (rápido, conserva todo) o limpias con down (elimina contenedores y red).

• Confundir down con stop: down elimina los contenedores y la red; stop solo los pausa. Si quieres reanudar luego, usa stop/start; si quieres limpiar, usa down.
• Perder datos con down -v: la opción -v borra los volúmenes y, con ellos, los datos de tus bases de datos. Úsala con plena conciencia.
• Olvidar --build tras cambiar el código: si no reconstruyes, Compose seguirá usando la imagen antigua y no verás tus cambios.
• Ejecutar comandos desde la carpeta equivocada: Compose busca el docker-compose.yml en el directorio actual; si no lo encuentra, fallará.
• Usar start con contenedores inexistentes: start solo reanuda contenedores que existen pero están detenidos. Si ya hiciste down, debes volver a up.
• Consejo: deja docker compose logs -f corriendo en una terminal mientras desarrollas; es la forma más rápida de enterarte de cualquier error en cuanto ocurre.

Arranca una aplicación Compose en segundo plano, comprueba que sus servicios están en ejecución y muestra los registros del servicio db en tiempo real.

Has modificado el código de tu servicio api. Escribe el comando que reconstruye su imagen y relanza la aplicación en segundo plano en un solo paso. Luego explica la diferencia entre docker compose stop y docker compose down.

Abre una shell interactiva dentro del contenedor del servicio web para inspeccionar sus archivos.

Solución al Ejercicio 1

• up -d arranca en segundo plano.
• ps confirma que los servicios están en estado running.
• logs -f db sigue en tiempo real los registros del servicio db.

Solución al Ejercicio 2

La opción --build fuerza la reconstrucción de las imágenes (incluida la de api) y -d la levanta en segundo plano, todo en un único comando.

Diferencia entre stop y down:

• stop: detiene los contenedores pero los conserva; puedes reanudarlos con start. No elimina la red ni los volúmenes.
• down: detiene y elimina los contenedores y la red por defecto. Los contenedores dejan de existir y, para volver a tenerlos, hay que ejecutar up de nuevo.

Solución al Ejercicio 3

Esto abre una shell (sh) dentro del contenedor en ejecución del servicio web. Si la imagen incluye Bash, también puedes usar docker compose exec web bash. Para salir, escribe exit.

En esta lección has aprendido a operar tus aplicaciones Compose con los comandos esenciales: arrancar con up (y su modo -d), apagar y limpiar con down, inspeccionar el estado con ps, leer registros con logs, depurar con exec, construir imágenes con build y controlar la ejecución con stop, start y restart. La tabla resumen y el ciclo de trabajo típico te servirán de referencia rápida cada vez que trabajes con Compose.

En la siguiente lección, Aplicaciones Multi-Contenedor, juntaremos todo lo aprendido para construir, paso a paso, una aplicación real completa con servicio web, base de datos y caché, viendo cómo se comunican los servicios entre sí por su nombre y cómo orquestar su arranque de principio a fin.