Con el fichero ya escrito, toca dominar la herramienta que lo interpreta. La CLI de Compose tiene unos veinticinco subcomandos, pero el reparto es muy desigual: usarás cinco a diario, otros cinco a menudo y el resto en situaciones concretas.

Esta lección los recorre por familias, siempre sobre el compose.yaml de Aurora Libros de la lección anterior. Presta especial atención a dos parejas que se confunden sin parar: up frente a start, y exec frente a run.

1. Tabla maestra de subcomandos
2. up: el comando que reconcilia
3. down y el peligro de -v
4. start, stop, restart, pause, create
5. Observación: ps, logs, top, stats, events
6. Ejecución puntual: exec frente a run
7. Construcción y publicación: build, pull, push
8. Escalado local con --scale y sus límites
9. Diagnóstico: config y validación en CI
10. Selección de ficheros y proyecto: -f, -p, COMPOSE_FILE
11. Autocompletado y alias útiles

Un comando que se olvida y es utilísimo: docker compose ls funciona desde cualquier directorio y te dice qué proyectos hay levantados en la máquina y con qué fichero.

docker compose up es el 80 % del uso diario. No es "arrancar": es llevar el estado real al estado declarado. En cada ejecución, para cada servicio, Compose calcula un resumen de su configuración (el config-hash que viste en la lección 04-01) y decide:

Esa selectividad es lo que hace que editar la memoria de la caché y ejecutar up -d recree solo la caché y no tire abajo la base de datos.

--wait es la opción que convierte a Compose en una herramienta de automatización: sin ella, el comando devuelve el control en cuanto los contenedores están arrancados, y un script de CI que lanza pruebas inmediatamente después se estrella contra una base de datos que aún no acepta conexiones. Con --wait, Compose no devuelve el control hasta que todas las sondas de salud pasan, y sale con código distinto de cero si alguna no lo consigue.

Sin -d, up deja el terminal enganchado a los logs agregados de todos los servicios y Ctrl+C para la pila entera. Es cómodo para depurar un arranque; peligroso si lo olvidas en una sesión SSH.

Un caso muy útil de --no-deps: recrear solo la API sin reiniciar la base de datos.

down es la inversa de up: para y elimina contenedores y redes del proyecto.

Grábate la segunda fila. docker compose down -v borra los volúmenes con nombre del proyecto sin preguntar: en Aurora Libros, eso es el catálogo entero de la librería. Es exactamente lo que quieres al resetear un entorno de desarrollo y exactamente lo que arruina un servidor si lo tecleas por inercia. Dos defensas: declarar los volúmenes críticos como external: true (lección 04-02) y no crear jamás un alias de shell que incluya -v.

La trampa de restart merece un aviso explícito: no relee el fichero. Si cambias una variable de entorno y ejecutas docker compose restart aurora-api, el contenedor se reinicia con la configuración antigua y te vuelves loco buscando por qué no se aplica el cambio. Para aplicar cambios del fichero, siempre up -d.

--services es oro para guiones: for s in $(docker compose ps --services); do ...; done.

Los logs son la herramienta que más usarás:

Compose colorea y prefija cada línea con el nombre del servicio, así que docker compose logs -f con la pila entera te deja ver el flujo de una petición atravesando web → api → db. Recuerda de la lección 03-04 que solo verás lo que los procesos escriban en stdout/stderr.

port responde a "¿en qué puerto del host está publicado el 80 de la web?", y es imprescindible cuando dejas que Docker asigne puertos aleatorios.

Es la distinción que más confusión genera, y la respuesta es simple: exec entra en un contenedor que ya está corriendo; run crea uno nuevo.

-T desactiva la asignación de pseudo-TTY: obligatorio cuando rediriges la salida a un fichero o encadenas tuberías, o el volcado saldrá con caracteres de control.

--rm casi siempre. Sin él, cada run deja un contenedor parado en la máquina; al cabo de una semana tienes cuarenta contenedores aurora-libros-aurora-api-run-a3f9c2 ocupando espacio. Y --no-deps cuando la tarea no necesita la pila: sin él, un run inocente te levanta PostgreSQL y Redis.

El flujo típico de CI, que verás completo en la lección 06-02, cabe en tres líneas: docker compose build, docker compose push y, en el servidor, docker compose pull && docker compose up -d.

Ahí está el primer choque: un puerto fijo del host no se puede repartir entre tres réplicas. Solo hay un 3000 en la máquina. Y si el servicio tuviera container_name, fallaría antes todavía, porque dos contenedores no pueden llamarse igual.

Quitando la publicación fija, funciona:

El DNS interno de Docker devuelve las tres direcciones para el mismo nombre, y el cliente elige una. Es un reparto rudimentario —sin comprobación de salud, sin pesos, sin reintentos— que sirve para pruebas locales, no para producción. El balanceo real, con sus estrategias y su gestión de réplicas caídas, es la lección 06-06.

docker compose config lee todos los ficheros implicados, interpola variables, fusiona overrides y muestra la configuración final tal y como la entiende Compose. Es tu única forma de ver la verdad.

En una tubería de CI, --quiet es la primera comprobación que debe correr, antes incluso de construir nada:

Dos avisos sobre config: resuelve las variables, así que su salida puede contener contraseñas en claro (nunca la vuelques en un log público), y muestra el resultado normalizado, con las formas cortas convertidas en formas largas. Esa normalización es justo lo que necesitas para entender qué hizo una fusión de anclas o de ficheros.

Las opciones globales van antes del subcomando:

Con varios -f, Compose fusiona los ficheros en el orden dado y el último gana en caso de conflicto. El mecanismo de fusión completo, con sus reglas por tipo de clave, es la lección 04-06.

Un detalle que sorprende: cuando usas -f, el directorio base para las rutas relativas pasa a ser el del primer fichero. Si tus ficheros están repartidos, --project-directory te deja fijarlo explícitamente.

Y la variable de entorno equivalente, útil para no repetir -f cien veces al día:

Con el autocompletado activo, docker compose logs -f aur<TAB> te ofrece los servicios reales del proyecto: se acabó teclear mal los nombres.

Ese último comentario no es una broma: la mayor parte de las pérdidas de datos con Compose vienen de un alias corto que alguien escribió con -v "para limpiar rápido".

Usar restart esperando que aplique cambios del fichero. No lo hace. Cambio en el compose.yaml → up -d, siempre.

Confundir stop con down. stop conserva los contenedores, down los elimina junto con la red. Si tras un down esperabas encontrar el contenedor parado, no está.

Teclear down -v por costumbre. Borra los volúmenes con nombre y con ellos los datos. Piénsalo cada vez.

Olvidar --rm en run. Cada ejecución deja un contenedor parado. Limpia los acumulados con docker compose rm -f.

Ejecutar exec con redirección sin -T. El pseudo-TTY inserta caracteres de control y corrompe volcados y ficheros binarios.

Poner -f después del subcomando. Las opciones globales van antes; el error que devuelve la CLI no siempre lo deja claro.

Consejo: cuando algo no se comporta como esperas, el orden de diagnóstico es docker compose config (¿qué entiende Compose?), docker compose ps (¿qué está corriendo?) y docker compose logs (¿qué dice el servicio?). En ese orden resuelves casi todo.

Ejercicio 1. Con la pila levantada, cambia el límite de memoria de aurora-cache de 256M a 320M y aplícalo sin que se reinicien los otros tres servicios. Demuestra con comandos que solo se recreó la caché y que el límite nuevo está activo.

Ejercicio 2. Escribe un guion verificar.sh apto para CI que: valide el fichero, levante la pila esperando a que esté sana, ejecute las pruebas de la API en un contenedor efímero, imprima el estado de los cuatro servicios y limpie todo, volúmenes incluidos, devolviendo el código de salida de las pruebas.

Ejercicio 3. Sin apagar la pila, obtén: (a) el número de claves en Redis, (b) los tres primeros títulos del catálogo ordenados alfabéticamente, y (c) un volcado de la tabla libros en el fichero ~/libros.sql del host. Explica qué opción es imprescindible en el tercer caso y por qué.

Solución 1.

Edita el límite en el compose.yaml (limits: { memory: 320M, cpus: "0.5", pids: 100 }) y aplica:

Ahí está la reconciliación: Recreated solo en la caché, Running en los otros tres porque su config-hash no cambió. Verificación:

La caché lleva cuatro segundos y los demás siguen con sus veintidós minutos. Y 335544320 bytes son exactamente 320 MiB. Ojo: recrear un contenedor no es reiniciarlo, es destruirlo y crear otro; los datos que no estén en un volumen se pierden. En Redis, eso significa una caché vacía, que aquí es inocuo porque /libros la repuebla desde la base de datos.

Solución 2.

Cuatro decisiones importantes: --quiet valida antes de gastar tiempo construyendo; --wait con --wait-timeout garantiza que las pruebas no arranquen contra una base de datos que aún no responde y falla con código distinto de cero si no lo consigue; --rm --no-deps en las pruebas evita dejar basura y no vuelve a levantar dependencias que ya están sanas; y down -v es aquí correcto y deseable, porque es un entorno desechable. Fíjate en que se guarda $? antes de los comandos de limpieza: si no, el código de salida que devuelve el guion sería el de down, y el pipeline pasaría siempre en verde.

Solución 3.

En el tercer caso -T es imprescindible. Sin él, Compose asigna un pseudo-TTY al comando y el flujo de salida deja de ser binario limpio: se traducen los saltos de línea y se cuelan secuencias de control, con lo que el .sql resultante puede no volver a importarse. La regla es sencilla: si la salida no la vas a leer tú con los ojos, -T.

Ya manejas la CLI completa. Sabes que up no es "arrancar" sino "reconciliar": compara el resumen de configuración de cada servicio con el declarado y recrea solo lo que cambió, lo que te permite ajustar un límite y tocar un único contenedor. Conoces sus opciones decisivas —-d, --build, --pull, --force-recreate, --no-deps, --remove-orphans y sobre todo --wait, que espera a que las sondas de salud pasen y falla si no lo hacen—. Y tienes claro qué borra cada variante de down, con -v marcado en rojo.

Distingues start/stop/restart/pause de up/down, con la trampa de que restart no relee el fichero. Observas con ps (incluidos --services y --format json), logs, top, stats, events y port. Y tienes interiorizada la diferencia clave: exec entra en lo que ya corre, run crea un contenedor nuevo, con --rm para no acumular basura, --no-deps para no levantar media pila y -T cuando rediriges la salida. Construyes y publicas con build/pull/push, escalas localmente con --scale sabiendo que choca con los puertos fijos y con container_name, validas con config --quiet en CI y controlas qué fichero y qué proyecto usas con -f, -p y COMPOSE_FILE.

En la lección siguiente, Aplicaciones Multi-Contenedor, todo esto se pone al servicio del montaje definitivo: la arquitectura de Aurora Libros con dos redes segmentadas —una frontal y una trasera marcada como internal—, el DNS de Compose y la tabla de quién habla con quién y por qué puerto, el orden de arranque resuelto con depends_on y condition: service_healthy usando pg_isready y redis-cli ping, un servicio de migración con service_completed_successfully, y el patrón de reintento con backoff que hace falta aunque tengas todo lo anterior. Al final, los quince pasos de onboarding se quedarán en dos.