La imagen auroralibros/aurora-api:1.2.0 pesa 142 MB. No es un desastre, pero tampoco está optimizada: dentro viaja un compilador de C, las dependencias de desarrollo y ficheros que nadie ejecuta. En esta lección la pones a dieta midiendo en cada paso, hasta una cifra concreta, sin perder nada del endurecimiento de la lección 05-03.

1. Por qué importa el tamaño y qué no hay que sacrificar
2. Medir primero: image ls e history
3. dive: explorar capa a capa
4. Elección de la base, con cifras
5. Construcciones multietapa: el concepto
6. Multietapa aplicada a aurora-api
7. Etapas con nombre y --target
8. Imagen base común para varias imágenes
9. Reducir capas y contenido
10. Borrar un fichero no reduce el tamaño (demostrado)
11. Ordenar para la caché
12. Verificación final y tabla resumen

En una plataforma con cinco nodos y quince despliegues al mes, bajar 40 MB por imagen son unos 3 GB menos de transferencia mensual y decenas de segundos menos en cada arranque en frío.

Y lo que no se sacrifica por bajar de peso: el HEALTHCHECK, el usuario sin privilegios, las etiquetas OCI de trazabilidad, la capacidad de diagnosticar un problema en producción y la reproducibilidad de la construcción. Una imagen de 40 MB que nadie sabe depurar a las tres de la madrugada es un mal negocio.

El diagnóstico es inmediato y sorprende a casi todo el mundo la primera vez: de los 142 MB, 115 MB son la imagen base. Las dependencias son 21 MB y el código propio, 3 MB. La palanca principal no está en tu código: está en qué base eliges y en qué añades encima.

Para comparar con precisión usa el tamaño real (docker image inspect --format '{{.Size}}' | numfmt --to=iec) y no el que muestra el registro, que está comprimido y siempre parece menor.

docker history dice cuánto pesa cada capa; dive dice qué hay dentro y cuánto se desperdicia.

Tres hallazgos y tres decisiones: la caché de npm no debería estar en la imagen final, node_modules/.cache es basura de compilación, y .git no debería haber entrado nunca en el contexto de construcción (falta una línea en .dockerignore).

El efficiency score mide cuánto contenido se escribe en una capa y se sobrescribe o borra en otra; por debajo del 95 % hay trabajo que hacer. Para automatizarlo en CI, añade -e CI=true y --lowestEfficiency=0.95: dive termina con código distinto de cero si no se alcanza el umbral.

La contrapartida de Alpine tiene nombre: musl en lugar de glibc. Consecuencias reales:

• Los paquetes npm con binarios precompilados para glibc pueden no funcionar y tener que compilarse al instalar (más lento, y exige build-base).
• Algunas cargas intensivas en DNS o en resolución de nombres se comportan de forma distinta con musl.
• Ciertas bibliotecas científicas y de aprendizaje automático no soportan musl.

aurora-api usa Express, pg y redis, ninguna con dependencias nativas problemáticas: Alpine es la elección correcta. Si un día una dependencia diera problemas, node:22-slim cuesta 95 MB más y los resuelve.

Una construcción multietapa usa varias imágenes base en el mismo Dockerfile. Las etapas intermedias compilan y preparan; la etapa final copia solo el resultado. Todo lo demás —compiladores, cachés, dependencias de desarrollo, código fuente— se queda fuera de la imagen publicada.

Dos reglas que resumen el mecanismo:

• Solo la última etapa (o la indicada con --target) acaba en la imagen; las demás se descartan.
• COPY --from=<etapa> trae ficheros concretos de una etapa anterior, y nada más viaja: ni sus capas, ni su historial, ni sus secretos.

Punto de partida (una sola etapa, 142 MB) y destino:

142 MB → 121 MB: un 15 % menos con un solo cambio estructural. ¿De dónde salen los 21 MB? De build-base (python3, make, g++), que se instalaba en la imagen final y ahora vive y muere en la etapa dependencias, y de la caché de npm.

Fíjate en que nada de lo endurecido se ha perdido: USER node, el HEALTHCHECK, las etiquetas OCI y el ENTRYPOINT/CMD en forma exec siguen ahí. Optimizar no es recortar seguridad.

Las etapas con nombre no son solo organización: son artefactos construibles por separado.

La imagen de desarrollo pesa 318 MB y está bien que así sea: lleva las devDependencies, el marco de pruebas y las herramientas de depuración. Es exactamente el target: desarrollo que compose.override.yaml usa desde la lección 04-07, y ahora ves de dónde sale.

Un patrón muy útil es una etapa de pruebas que falla la construcción si las pruebas fallan:

BuildKit no ejecuta esa etapa al construir la de producción, porque no forma parte de su grafo de dependencias (lección 05-05). Solo se ejecuta si la pides con --target.

Cuando publicas varios servicios en Node, conviene una base propia con lo compartido:

Ventajas: una sola actualización de seguridad se propaga a todos los servicios, la capa base se comparte en disco y en la descarga entre ellos, y las decisiones comunes están en un solo sitio. Inconveniente: creas una dependencia interna que hay que mantener y versionar. Compensa a partir de tres o cuatro servicios.

El .dockerignore de aurora-api tras lo que reveló dive:

De 94 MB de directorio a 812 kB de contexto. Eso no solo hace la construcción más rápida: garantiza que .git y .env no puedan colarse en ninguna capa, que es un asunto de seguridad además de tamaño.

El fichero no existe y la imagen sigue pesando 113 MB. La explicación es la de la lección 05-02: las capas son inmutables y rm en una capa posterior solo crea un whiteout que oculta el fichero; los 105 MB siguen ahí abajo, se descargan en cada pull y se almacenan en cada nodo.

La corrección es unir creación y borrado en la misma instrucción:

De 113 MB a 8,15 MB. La misma lógica, el mismo resultado funcional, un && de diferencia. Y es exactamente el motivo de --virtual .build en el Dockerfile del apartado 6: instalar, compilar y desinstalar dentro de un solo RUN.

Recordatorio de la lección 02-02, ahora combinado con multietapa: las instrucciones se ordenan de menos a más cambiante.

Con multietapa el efecto se multiplica: al tocar src/server.js, BuildKit reutiliza toda la etapa dependencias —incluida la instalación de npm— y solo rehace las dos últimas capas de la etapa final.

Tres segundos frente a los cuarenta y tantos de una construcción limpia. Optimizar el tamaño y optimizar la velocidad de construcción son, casi siempre, el mismo trabajo.

Una imagen optimizada que no funciona no vale nada. La comprobación es obligatoria:

Y el último escalón, si tu contexto lo permite: cambiar la base final a distroless.

142 MB → 102 MB: un 28 % menos. El precio, ya conocido de la lección 05-03: sin sh no hay docker exec ... sh y el HEALTHCHECK con wget deja de funcionar, así que la sonda pasa a hacerse desde Compose o desde el orquestador.

Optimizar sin medir. Sin docker history y dive, se recorta donde no duele y se deja intacta la capa de 100 MB.

Borrar ficheros en un RUN posterior. El fichero desaparece y el espacio no. Creación y borrado, en la misma instrucción.

Copiar todo el proyecto con COPY . . sin .dockerignore. Entran .git, node_modules y, con suerte, algún .env.

Instalar herramientas de compilación en la imagen final. Compiladores en producción son peso y superficie de ataque. Van en la etapa de dependencias.

Sacrificar el HEALTHCHECK o el USER por ahorrar unos megas. El intercambio es pésimo: la seguridad y la operabilidad valen más que 3 MB.

Perseguir el mínimo absoluto. Un binario en scratch que no puedes depurar cuesta más caro en la primera incidencia de lo que ahorró en un año de descargas.

Consejo: integra la medición en el flujo de trabajo. Un paso de CI que compare el tamaño de la imagen con el de la versión anterior y avise si crece más de un 10 % detecta la dependencia inflada el día que entra, no seis meses después.

Ejercicio 1. Analiza auroralibros/aurora-api:1.2.0 con history y con dive: identifica la capa más grande, calcula qué porcentaje del total representa la base, y encuentra al menos un desperdicio real que puedas eliminar con .dockerignore.

Ejercicio 2. Convierte el Dockerfile de aurora-api a multietapa con tres etapas (dependencias, desarrollo, produccion), mide el antes y el después, y demuestra que la imagen final no contiene el compilador que sí está en la etapa de dependencias.

Ejercicio 3. Demuestra que borrar un fichero en una capa posterior no reduce el tamaño y arréglalo. Calcula el ahorro exacto y explica qué habría pasado si ese fichero hubiera sido un fichero de credenciales.

Solución 1.

El 81 % de la imagen es la base. Es el dato que reordena las prioridades: pelear por los 3 MB del código propio es irrelevante mientras no se decida conscientemente qué base se usa. Con dive aparece el desperdicio concreto:

.git dentro de una imagen de producción no es solo 1,2 MB de peso: es el historial completo del repositorio viajando en el registro, con cualquier secreto que alguien commiteara y luego borrara. Se corrige con una línea en .dockerignore, y la comprobación es directa:

Solución 2.

La etapa dependencias tiene los tres binarios de compilación; la final, ninguno. Y sin embargo ambas tienen los mismos 64 paquetes en node_modules: COPY --from=dependencias ha traído exactamente el resultado del trabajo y nada del utillaje que lo produjo.

Esa es la idea central de multietapa expresada de la forma más clara posible: lo que necesitas para construir no es lo que necesitas para ejecutar. Y el beneficio no es solo de tamaño; también es de seguridad, porque un atacante con ejecución de comandos en la imagen final no encuentra un compilador con el que preparar la siguiente fase de su ataque.

Solución 3.

El ahorro exacto son 104,85 MB, un 92,8 % del total, y el resultado funcional es idéntico: en ambas imágenes el fichero no existe. La diferencia está en si los 100 MB llegaron a formar parte de una capa consolidada. En mal, la capa A los escribió y quedaron inmutables; la capa B solo añadió un whiteout que los oculta. En bien, el fichero nació y murió dentro de la misma instrucción, así que cuando BuildKit consolidó la capa ya no estaba.

La pregunta sobre las credenciales lleva la demostración a su conclusión más incómoda:

El fichero no existe y la contraseña se recupera de la capa exportada en un solo comando. Si esa imagen se hubiera publicado en Docker Hub, cualquiera podría extraerla con docker pull y docker save, sin necesidad de ejecutar el contenedor. Por eso el mismo && que ahorra 105 MB es también un control de seguridad, y por eso la solución correcta para los secretos de construcción no es un && sino RUN --mount=type=secret, que verás en la lección siguiente.

aurora-api ha pasado de 142 MB a 102 MB, un 28 % menos, sin perder el usuario sin privilegios, el HEALTHCHECK, las etiquetas OCI ni un solo endpoint: /salud, /libros y /libros/:id responden igual y el contenedor sigue llegando a healthy. Y, más importante que la cifra, tienes el método: medir primero. docker image ls para el total, docker image history para encontrar la capa gorda —que resultó ser la base, con el 81 % del peso— y dive para ver el desperdicio real, que destapó la caché de npm y un .git que nunca debió entrar en el contexto.

Sabes elegir la base con criterio y no por costumbre, conociendo la contrapartida de musl frente a glibc y qué cuesta cada escalón entre node:22, -slim, -alpine, distroless y scratch. Dominas las construcciones multietapa: una etapa que instala y compila con build-base, una de desarrollo con las devDependencies que alimenta el target: desarrollo de tu compose.override.yaml, una etapa de pruebas que rompe la construcción si algo falla, y una final que solo recibe node_modules y src/ mediante COPY --from —demostrado: tres compiladores en la etapa intermedia, cero en la publicada—. Y sabes construir cada una por separado con --target, además de compartir una imagen base propia entre varios servicios.

Del lado del contenido: --no-cache, --no-install-recommends, --virtual con su apk del, npm ci --omit=dev, npm cache clean y un .dockerignore que redujo el contexto de 94 MB a 812 kB. Y la demostración que más vale la pena recordar: borrar un fichero en una capa posterior no reduce el tamaño —113 MB frente a 8,15 MB por un &&—, y ese mismo mecanismo hace que una credencial escrita y borrada siga siendo extraíble de la imagen publicada.

En la lección 05-05 entra en escena el constructor que ha estado haciendo todo esto por debajo: BuildKit, con su grafo de dependencias y su paralelismo entre etapas, y Buildx con sus builders. Verás los montajes en RUN —type=cache para no reinstalar npm en cada build, type=bind, type=tmpfs y sobre todo type=secret, la respuesta correcta al problema de credenciales que acabas de demostrar—, la caché remota compartida con --cache-from y --cache-to, la compilación multiarquitectura para amd64 y arm64 con sus manifest lists, y docker buildx bake para construir todas las imágenes de Aurora Libros de una sola vez.