En la lección anterior construiste auroralibros/aurora-api:0.1.0 con un Dockerfile que se te dio hecho y se te explicó por encima. Funciona, arranca la API dentro de un contenedor y responde a curl. Pero lo escribiste casi a ciegas: sabes qué hace cada línea, no por qué está escrita exactamente así. Esta lección salda esa deuda. Vas a recorrer el lenguaje del Dockerfile instrucción por instrucción, con el nivel de detalle que en 02-02 quedó pendiente: por qué WORKDIR es mejor que RUN cd, en qué se diferencian COPY y ADD y por qué casi siempre gana COPY, qué significan exactamente las dos formas de RUN y de CMD, por qué encadenar comandos con && produce imágenes más pequeñas, por qué EXPOSE no expone nada, y qué le pasa a tu contenedor cuando lo paras según cómo hayas escrito el CMD. Al final construirás el Dockerfile definitivo de aurora-api, comentado línea a línea y con cada decisión justificada.

1. Estructura de un Dockerfile, comentarios y la directiva # syntax
2. Tabla resumen de las instrucciones básicas
3. FROM: de dónde partes
4. WORKDIR: dónde trabajas
5. COPY: qué traes del contexto
6. COPY frente a ADD
7. RUN: qué ejecutas durante la construcción
8. ENV: configuración que sobrevive a la construcción
9. EXPOSE: documentación, no publicación
10. CMD: qué proceso arranca el contenedor
11. El Dockerfile definitivo de aurora-api

Un Dockerfile es un fichero de texto plano, sin extensión, con una instrucción por línea:

Reglas de sintaxis:

• Las instrucciones se escriben en MAYÚSCULAS por convención. from node:22-alpine funciona igual, pero nadie lo escribe así: en mayúsculas se distingue de un vistazo la instrucción de sus argumentos.
• Una instrucción por línea. Para partir una línea larga se usa la barra invertida \ al final, sin nada después (ni siquiera un espacio: un espacio tras la barra invierte su efecto y produce errores desconcertantes).
• Las líneas que empiezan por # son comentarios, salvo las directivas del apartado siguiente. Como comprobaste en el ejercicio 2 de la lección 02-02, los comentarios no afectan a la caché.
• El orden importa, y no solo por la caché: cada instrucción se ejecuta sobre el estado que dejó la anterior.
• Las líneas vacías se ignoran. Úsalas para agrupar bloques lógicos; un Dockerfile bien espaciado se lee muchísimo mejor.

La primera línea del fichero merece un apartado propio:

No es un comentario: es una directiva del intérprete. Le dice a BuildKit qué versión del frontend de Dockerfile debe usar para interpretar el resto del fichero. BuildKit descarga esa imagen del registro y la usa como analizador sintáctico.

Por qué conviene ponerla siempre:

• Te da las funcionalidades más recientes sin actualizar Docker. docker/dockerfile:1 es una etiqueta móvil que apunta a la última versión estable de la serie 1. Cosas como COPY --link, los montajes de caché o los secretos de build (lección 05-05) dependen de ella.
• Hace el fichero portable. El mismo Dockerfile se interpreta igual en tu portátil y en un agente de CI con otra versión de Docker.
• Es compatible hacia atrás. La serie 1 garantiza que no romperá los Dockerfiles existentes.

Las variantes que verás:

Debe ser la primera línea del fichero (antes de cualquier instrucción, incluso antes de otros comentarios) para que surta efecto.

Estas son las instrucciones que cubre esta lección, con lo esencial de cada una:

La columna "¿Crea capa?" explica una observación de la lección 01-05: no todas las instrucciones engordan la imagen. COPY, ADD y RUN modifican el sistema de archivos y generan capas con contenido real; las demás solo escriben metadatos en el manifiesto, y su capa pesa cero bytes.

La columna "¿Cuándo actúa?" es la que más confusión evita. RUN se ejecuta al construir y su resultado queda congelado; CMD no se ejecuta al construir en absoluto, solo describe qué hará el contenedor al arrancar. Confundirlas es el error conceptual número uno de quien empieza.

Hay más instrucciones —ARG, ENTRYPOINT, USER, LABEL, HEALTHCHECK, VOLUME, STOPSIGNAL, ONBUILD, SHELL—, y todas se ven en la lección siguiente, la 02-04.

FROM es obligatoria y debe ser la primera instrucción (salvo directivas y comentarios). Establece el sistema de archivos y los metadatos de partida: todo lo que venga después se construye encima de esas capas.

Sintaxis completa:

Formas que verás, aplicadas a Aurora Libros:

El compromiso entre reproducibilidad y mantenimiento es real y no tiene una respuesta única:

Aurora Libros usa node:22-alpine, decidido en la lección 01-07 por tres motivos que ahora puedes justificar del todo: cumple el engines: node >=22.0.0 del package.json, es imagen oficial (espacio library/, primer criterio de confianza de la lección 02-01) y pesa ~142 MB frente a los ~1,1 GB de node:22. La contrapartida es que Alpine usa musl en lugar de glibc como biblioteca C; las tres dependencias del proyecto (express, pg, redis) son JavaScript puro o traen binarios compatibles, así que no supone problema.

La cláusula AS <nombre> da nombre a una etapa de construcción. Sirve para las builds multi-etapa, la técnica que permite compilar en una imagen y llevarse solo el resultado a otra mucho más pequeña. Se estudia en la lección 05-04; menciónala mentalmente y sigue.

WORKDIR fija el directorio de trabajo para todas las instrucciones posteriores que lo usen: RUN, COPY, ADD y CMD. Si no existe, lo crea, incluidos los directorios intermedios.

Es la pregunta obligada. Compara:

En el primer caso, npm ci se ejecuta en /, no en /app, y falla con ENOENT: no such file or directory, open '/package.json'. La razón es fundamental: cada RUN se ejecuta en un contenedor temporal nuevo. El cd cambia el directorio del shell de ese contenedor efímero, que muere en cuanto termina la instrucción; el siguiente RUN arranca de cero, en el directorio de trabajo heredado de la imagen.

La única forma de que cd sirva es encadenarlo dentro del mismo RUN:

Aun así, WORKDIR gana por cuatro razones:

1. Persiste en tiempo de ejecución. Es el directorio donde entras con docker exec -it aurora-api sh y donde se ejecuta el CMD. Un cd dentro de un RUN no deja rastro.
2. Crea el directorio si no existe, sin necesidad de mkdir -p.
3. Es un metadato visible. docker image inspect te dice cuál es; un cd enterrado en un RUN hay que ir a buscarlo.
4. Se lee mejor. Declara la intención en lugar de esconderla dentro de una cadena de comandos.

Detalles adicionales:

Usa siempre rutas absolutas. Las relativas encadenadas obligan a llevar la cuenta mental de dónde estás y son una fuente clásica de errores en Dockerfiles largos.

Para Aurora Libros, /app es la convención habitual en imágenes de Node. Cualquier ruta valdría (/srv/aurora, /usr/src/app), pero /app es corta, inequívoca y no colisiona con el sistema de archivos de Alpine.

COPY trae ficheros y directorios desde el contexto de construcción hasta el sistema de archivos de la imagen.

Reglas que hay que tener claras:

• El origen es siempre relativo a la raíz del contexto, jamás a tu directorio actual ni a la ubicación del Dockerfile. Y nunca puede salir del contexto: es la restricción que provocó el error "/db/init.sql": not found de la lección 02-02.
• El destino es relativo al WORKDIR si no es absoluto. Con WORKDIR /app, el destino ./ significa /app/.
• Si el destino termina en /, se trata como directorio; si no, y hay un solo origen, se interpreta como el nombre del fichero destino. Poner siempre la barra final evita sorpresas.
• Con varios orígenes, el destino debe ser un directorio y acabar en /.
• COPY copia el contenido de un directorio, no el directorio. COPY web/ /public/ deja el contenido de web/ directamente en /public/, no en /public/web/. Es la fuente número uno de rutas que "no aparecen" dentro de la imagen.

Ejemplos con Aurora Libros:

Sobre COPY package*.json ./: el comodín cubre package.json y package-lock.json de una vez. Tiene una ventaja práctica sobre nombrarlos por separado: no falla si package-lock.json no existe, porque el patrón simplemente coincide con menos ficheros. En cambio, COPY package.json package-lock.json ./ da error si falta el lock. Ambas formas son defendibles: la explícita detecta antes el olvido del lock (que rompería el npm ci), la del comodín es más tolerante. Aurora Libros usará la del comodín, que es la convención más extendida en el ecosistema Node.

Por defecto, todo lo copiado pertenece a root:root. --chown cambia el propietario en la misma operación:

La imagen node:22-alpine incluye ya un usuario node sin privilegios. Copiar directamente con su propiedad evita un RUN chown -R node:node /app posterior, que duplicaría el tamaño de esa capa: cambiar los permisos de un fichero lo marca como modificado y el copy-on-write de la lección 01-05 obliga a escribir una copia entera en la capa nueva. Un chown recursivo sobre node_modules puede añadir decenas de megas a la imagen.

--chmod hace lo propio con los permisos:

El uso de USER para ejecutar el contenedor sin privilegios se ve en la lección 02-04, y el porqué en profundidad, en la 05-03.

ADD existe desde el primer día de Docker y hace todo lo que hace COPY, más dos cosas extra. Precisamente por eso conviene evitarla.

El problema de ADD es que su comportamiento depende de lo que le pases:

Tres comportamientos distintos con la misma instrucción. Quien lee el Dockerfile tiene que saber de memoria qué formatos se descomprimen para predecir el resultado. COPY siempre hace exactamente lo mismo: copiar.

Y el caso de la URL es peor:

Cuatro problemas acumulados: el .tar.gz queda para siempre en la capa del ADD aunque lo borres después (copy-on-write, lección 01-05), no puedes verificar la suma de comprobación antes de usarlo, ADD no descomprime lo que viene de una URL (solo lo local), y no controlas cabeceras ni autenticación. La forma correcta, todo en un único RUN:

Aquí sí verificas el hash, y el borrado ocurre dentro de la misma capa, así que el fichero temporal no engorda la imagen.

La regla práctica: usa COPY siempre. El único caso donde ADD aporta algo genuino es descomprimir un tarball local del contexto, que ahorra tener tar en la imagen:

En el Dockerfile de aurora-api no aparece ningún ADD: no hay tarballs ni descargas.

RUN ejecuta un comando en el momento de construir la imagen, dentro de un contenedor temporal basado en las capas anteriores, y congela el sistema de archivos resultante en una capa nueva. Es la instrucción que instala paquetes, compila, genera ficheros… y la que más peso añade.

Para RUN, la forma shell es la habitual, porque casi siempre quieres encadenar comandos o expandir variables. La forma exec solo hace falta en imágenes sin shell (scratch, distroless) o cuando un argumento contiene caracteres que el shell interpretaría mal.

Ojo con la comilla: la forma exec es JSON, así que exige comillas dobles. RUN ['npm', 'ci'] con comillas simples no es JSON válido y BuildKit lo tratará como forma shell, con resultados desconcertantes.

Esta es la parte que de verdad importa. Cada RUN crea una capa. Compara:

Dos problemas en la versión mala, y el segundo es el grave:

1. Cuatro capas donde bastaba una. Más metadatos, más entradas en el manifiesto, más lentitud al montar la imagen.
2. El rm -rf del final no libera nada. Recuerda de la lección 01-05: las capas son diffs y solo se apilan. Borrar un fichero en la capa 4 no lo elimina de la capa 2; solo escribe un marcador de borrado que lo oculta. El fichero sigue viajando dentro de la imagen, ocupando su espacio en cada descarga.

Compruébalo tú mismo:

48 MB de diferencia por mover un rm de una línea a otra. El fichero borrado "existe" igualmente dentro de la imagen mal, invisible pero descargable.

De ahí las tres reglas de oro de RUN:

1. Agrupa las operaciones relacionadas en un solo RUN con && y \.
2. Limpia en la misma capa donde ensucias. Cachés de gestores de paquetes, ficheros temporales, código fuente que ya has compilado.
3. Pero no lo agrupes todo. Si metes en un único RUN la instalación de dependencias y el arranque de la aplicación, pierdes granularidad de caché. El equilibrio: un RUN por propósito.

Un aviso sobre Debian: apt-get update y apt-get install deben ir siempre en el mismo RUN. Si los separas, la caché puede reutilizar un update de hace semanas mientras ejecuta un install nuevo, y acabarás instalando versiones que ya no están en los repositorios. Es el clásico error conocido como cache busting de apt.

Desmenuzado:

• npm ci en lugar de npm install. ci significa clean install: borra node_modules si existe e instala exactamente las versiones fijadas en package-lock.json, sin resolver rangos. Si el lock y el package.json no concuerdan, falla en lugar de improvisar. Eso es justo lo que quieres en una imagen: dos builds del mismo commit producen los mismos bytes. npm install, en cambio, puede resolver ^4.21.2 a 4.21.2 hoy y a 4.22.0 el mes que viene, produciendo imágenes distintas del mismo código.
• --omit=dev excluye las devDependencies. En Aurora Libros hoy no hay ninguna, pero en cuanto entren linters o frameworks de test, esta opción evitará que viajen a producción. Sustituye a la antigua --production, ahora desaconsejada.
• npm cache clean --force borra la caché que npm deja en ~/.npm, que puede rondar los 50 MB. Va en el mismo RUN por todo lo explicado arriba: en un RUN aparte no ahorraría un solo byte.

ENV define variables de entorno que existen durante el resto de la construcción y también dentro del contenedor en ejecución. Esa doble vida es su rasgo distintivo, y es lo que la diferencia de ARG (lección 02-04).

Sintaxis:

Usa siempre la forma con =. La antigua es ambigua con valores que contienen espacios y está en desuso.

Las variables definidas se pueden usar en instrucciones posteriores:

Y persisten en ejecución. Compruébalo con la imagen que ya tienes:

Lo importante es que son valores por defecto sobrescribibles al arrancar el contenedor:

Ese -e tiene prioridad sobre el ENV de la imagen. Es exactamente el mecanismo que hace que el server.js de la lección 01-07 —que lee toda su configuración de process.env— sirva sin cambios en tu portátil y en producción.

La última fila es la regla que arrastras desde la lección 01-07 y que ahora puedes demostrar. Si alguien escribiera ENV DB_PASSWORD=superSecreta2026, cualquiera con acceso a la imagen la vería:

Ahí está todo, en claro, sin necesidad ni de arrancar el contenedor. Y publicando la imagen en el repositorio público auroralibros/aurora-api, en Internet.

NODE_ENV=production merece un comentario porque en Node no es decorativo: Express desactiva vistas de depuración y cachea plantillas, muchas librerías reducen el registro y npm install omitiría las devDependencies. Es un cambio de comportamiento real, no una etiqueta.

Aquí está la trampa que atrapa a todo el mundo. Leyendo "expose" cualquiera entiende "abre este puerto al exterior". EXPOSE no abre nada, no publica nada y no cambia el comportamiento de la red. Es exclusivamente documentación en forma de metadato.

Lo que sí hace:

• Deja constancia en los metadatos de la imagen de qué puerto usa el servicio, para que quien la ejecute lo sepa sin leer el código.
• Aparece en docker image inspect y en la columna PORTS de docker ps.
• Habilita la opción docker run -P (mayúscula), que publica todos los puertos declarados con EXPOSE en puertos aleatorios altos del host.
• Docker Compose y algunos orquestadores lo leen como pista.

Lo que no hace: publicar el puerto. Eso sigue siendo trabajo exclusivo de -p en docker run, tal como aprendiste en la lección 01-06.

Demuéstralo. Tu imagen 0.1.0 tiene EXPOSE 3000. Arráncala sin -p:

Fíjate en la columna PORTS: pone 3000/tcp, sin ninguna flecha ->. Eso significa "el contenedor declara este puerto", no "está publicado". Compruébalo:

Ahora con -P mayúscula, que sí publica lo declarado:

Ahora sí hay flecha: el puerto 3000 del contenedor está publicado en el 32768 del host, elegido al azar. Limpia:

Entonces, ¿para qué molestarse en poner EXPOSE? Por tres razones sólidas:

1. Documenta la interfaz de la imagen. Quien la reciba sabe qué puerto mapear sin leer server.js.
2. Es el contrato con el orquestador. Compose (módulo 4), Swarm y Kubernetes (módulo 6) lo usan como referencia.
3. Cuesta cero. Es un metadato: no añade un solo byte a la imagen.

Sintaxis completa:

CMD define el comando por defecto que se ejecuta al arrancar un contenedor a partir de la imagen. No se ejecuta durante la construcción: solo se guarda como metadato.

Y hay una regla que gobierna todo lo demás, ya vista en la lección 01-06: el contenedor vive mientras viva su proceso principal. Cuando el proceso del CMD termina, el contenedor se para. Por eso CMD ["node", "server.js"] mantiene el contenedor vivo (el servidor no termina) y CMD ["echo", "hola"] produce un contenedor que muere al instante.

Parecen equivalentes, y en condiciones normales lo son. La diferencia aparece al parar el contenedor, y es lo bastante importante como para verla en detalle.

Con la forma exec, Docker ejecuta node server.js directamente. El proceso node es el PID 1 dentro del contenedor.

Con la forma shell, Docker ejecuta /bin/sh -c "node server.js". El PID 1 es sh, y node es un proceso hijo:

Cuando ejecutas docker stop, Docker envía SIGTERM al PID 1 y espera 10 segundos antes de enviar SIGKILL. Con la forma exec, node recibe el SIGTERM y puede cerrar conexiones, vaciar búferes y terminar. Con la forma shell, el SIGTERM lo recibe sh, que no lo reenvía a sus hijos: node no se entera de nada, sigue trabajando, y a los 10 segundos lo mata un SIGKILL que no admite limpieza. Peticiones cortadas a la mitad y transacciones a medias.

Mídelo:

0,3 segundos frente a 10,2. Diez segundos de diferencia por unos corchetes, multiplicados por cada contenedor en cada despliegue. En un despliegue continuo con veinte réplicas (módulo 6), esa diferencia es la que separa un rollout limpio de uno con errores para los usuarios.

Limpia:

Regla: usa siempre la forma exec, con corchetes y comillas dobles. Es JSON: las comillas simples no valen.

• Solo la última cuenta. Si escribes varios CMD, los anteriores se descartan sin aviso.
• Se sobrescribe desde la línea de comandos. Todo lo que pongas tras el nombre de la imagen reemplaza al CMD:

No ha arrancado el servidor: has sustituido el CMD por node --version. Esta flexibilidad es útil para depurar (docker run --rm -it tuimagen sh te da una shell dentro de la imagen) y es la base del patrón ENTRYPOINT + CMD de la lección 02-04.

• Si la imagen base tiene un ENTRYPOINT, el CMD se convierte en sus argumentos. Es justo el tema de 02-04.
• No uses CMD para varios procesos. CMD ["sh", "-c", "node server.js & nginx"] es un antipatrón: un contenedor, un proceso. Aurora Libros tiene cuatro servicios porque tendrá cuatro contenedores.

Ya puedes justificar cada línea. Este es el Dockerfile final del módulo, que sustituye al mínimo de la lección 02-02. Guárdalo en ~/aurora-libros/api/Dockerfile:

Construye la versión 1.0.0, que es la que acompaña al version del package.json:

Cambia el código y reconstruye, que es lo que harás cincuenta veces al día:

1,2 segundos, con el npm ci intacto en la caché. El orden de las instrucciones —dependencias arriba, código abajo— hace exactamente lo que se diseñó.

Verifica la imagen terminada:

Todos los metadatos que has ido declarando están ahí, legibles. Y ninguna credencial entre ellos, como marca la regla del proyecto. Última comprobación funcional:

Igual que en 02-02: el servicio vive y responde; las dependencias siguen sin existir, y eso es el módulo 3.

• RUN cd /app esperando que persista. Cada RUN corre en un contenedor temporal distinto. Usa WORKDIR.
• CMD en forma shell. Diez segundos extra en cada parada y señales que nunca llegan a tu proceso. Usa siempre CMD ["ejecutable", "arg"] con comillas dobles: es JSON, no Python.
• Creer que EXPOSE publica el puerto. No publica nada. EXPOSE documenta; -p publica. Si tu servicio "no responde" y en docker ps no ves la flecha -> en PORTS, ese es el problema.
• Limpiar en un RUN distinto del que ensucia. El borrado no libera nada: la capa inferior conserva los ficheros. Encadena con && en la misma instrucción.
• apt-get update y apt-get install en RUN separados. La caché reutiliza un índice viejo y el install falla o instala versiones obsoletas. Siempre juntos.
• npm install en lugar de npm ci. Rompe la reproducibilidad: el mismo commit puede producir imágenes distintas. Y no olvides --omit=dev.
• ADD por costumbre. Su comportamiento depende del tipo de fichero y esconde descargas remotas sin verificar. Usa COPY salvo que necesites descomprimir un tarball local.
• Secretos en ENV. Quedan en los metadatos, visibles con docker image inspect sin siquiera arrancar el contenedor, y viajan con la imagen a donde vaya. Nunca.
• COPY . . sin .dockerignore. Ya lo viste en 02-02: contexto hinchado, caché rota y riesgo de filtrar un .env.
• Consejo: comenta el por qué, no el qué. # Instala dependencias sobra: se ve. # El cache clean va aquí para que libere espacio de verdad es lo que agradecerá quien lo lea dentro de seis meses.
• Consejo: lee Dockerfiles ajenos. Los de las imágenes oficiales están en GitHub (lección 02-01) y son una escuela excelente.

Construye dos imágenes basadas en node:22-alpine que instalen el paquete git con apk:

• Versión A: apk add git en un RUN y rm -rf /var/cache/apk/* en otro RUN posterior.
• Versión B: todo encadenado con && en un único RUN, usando apk add --no-cache.

Compara los tamaños con docker image ls y usa docker image history para localizar la capa culpable de la diferencia. Explica el resultado en términos de capas y copy-on-write.

1. Escribe dos Dockerfiles idénticos salvo el CMD: uno en forma exec y otro en forma shell, ambos arrancando node server.js desde la imagen de Aurora Libros.
2. Arranca un contenedor de cada uno.
3. Con docker exec <contenedor> ps -o pid,comm, comprueba qué proceso es el PID 1 en cada caso.
4. Cronometra docker stop en los dos con time.
5. Explica por qué la diferencia es de exactamente unos 10 segundos y no de un valor arbitrario, y qué opción de docker stop permitiría cambiar esa espera.

Este Dockerfile de la API de Aurora Libros tiene siete problemas relacionados con lo visto. Identifícalos, explica la consecuencia de cada uno y escribe la versión corregida.

Solución al ejercicio 1

Cuatro megas de diferencia (con paquetes más grandes, la diferencia llega a decenas o cientos). Localiza la capa culpable:

La lectura es concluyente: la capa del rm -rf pesa 0 B. No ha liberado nada. Solo ha escrito marcadores de borrado (whiteouts) que ocultan los ficheros de la capa inferior, pero esa capa de 19,2 MB sigue en la imagen y se descarga entera en cada docker pull.

En la versión B, --no-cache hace que apk no escriba nunca el índice en disco, así que no hay nada que borrar. Es la aplicación directa del copy-on-write de la lección 01-05: una capa solo puede añadir contenido u ocultarlo, nunca reducir el tamaño de las capas anteriores. De ahí la regla: ensucia y limpia en la misma instrucción.

Solución al ejercicio 2

3. Los procesos:

Confirmado: en la forma exec node es el PID 1; en la forma shell el PID 1 es sh y node es su hijo con PID 7.

4. Los tiempos:

5. La diferencia es de ~10 segundos exactos porque ese es el valor del temporizador de gracia de docker stop: envía SIGTERM al PID 1, espera 10 segundos y, si el contenedor sigue vivo, envía SIGKILL.

• En la forma exec, node recibe el SIGTERM. Aunque este server.js no instale un manejador explícito, el comportamiento por defecto de Node ante SIGTERM es terminar de inmediato: 0,3 s.
• En la forma shell, sh recibe el SIGTERM y no lo reenvía a sus hijos (un shell POSIX mínimo no hace reenvío de señales). node nunca se entera. Se agotan los 10 segundos y llega el SIGKILL, que el proceso no puede capturar: cierre abrupto, conexiones cortadas, sin oportunidad de vaciar búferes ni cerrar el pool de PostgreSQL.

El plazo se puede ajustar con docker stop -t <segundos>:

Bajar el plazo no resuelve nada: el proceso sigue sin recibir la señal. La solución es la forma exec, o un ENTRYPOINT con un script que use exec "$@" (lección 02-04). Limpieza:

Solución al ejercicio 3

Los siete problemas:

Un octavo detalle menor: ENV NODE_ENV production usa la sintaxis antigua sin =, desaconsejada por ambigua.

Versión corregida:

La contraseña se inyecta al ejecutar, nunca al construir:

Y en el módulo 4 ni siquiera irá en la línea de comandos, sino en un fichero .env fuera del control de versiones (lección 04-05) o en un secreto gestionado (lección 05-03).

Ya dominas el lenguaje del Dockerfile. Sabes que la directiva # syntax=docker/dockerfile:1 te da el intérprete más reciente sin actualizar Docker, y que de las ocho instrucciones básicas solo COPY, ADD y RUN engordan la imagen: las demás escriben metadatos que no pesan nada. FROM fija el punto de partida y el compromiso entre reproducibilidad y parches automáticos. WORKDIR sustituye a un RUN cd que nunca funcionaría, porque cada RUN vive en un contenedor temporal distinto, y además persiste en ejecución. COPY resuelve sus rutas contra el contexto y copia el contenido de los directorios; ADD añade descompresión y descargas con un comportamiento variable que la hace peor opción salvo para tarballs locales.

Con RUN has visto la regla más rentable de todas: limpia en la misma capa donde ensucias, porque una capa solo puede añadir u ocultar, nunca adelgazar a las anteriores —48 MB de diferencia en la demostración con python3—. Con ENV has distinguido lo que es un valor por defecto legítimo (NODE_ENV, PORT) de lo que jamás debe entrar en una imagen (DB_PASSWORD), y lo has comprobado leyendo los metadatos con docker image inspect. Con EXPOSE has desmontado la trampa del nombre: documenta, no publica, y la prueba es la ausencia de flecha -> en docker ps. Y con CMD has medido en carne propia que la forma exec y la forma shell no son estilos alternativos: son 0,3 segundos frente a 10,2 al parar el contenedor, porque el PID 1 es node o es sh, y sh no reenvía SIGTERM.

El resultado es auroralibros/aurora-api:1.0.0: 167 MB, comentada línea a línea, con cada decisión justificada, que se reconstruye en 1,2 segundos tras un cambio de código y que no lleva un solo secreto dentro. Es un Dockerfile que funciona.

En la siguiente lección, Instrucciones Avanzadas del Dockerfile, lo convertirás en uno profesional. Aprenderás a parametrizar la versión base con ARG y a distinguirlo de ENV, a separar el ejecutable fijo de sus argumentos con ENTRYPOINT y CMD combinados, a dejar de ejecutar la API como root con USER, a describir la imagen con etiquetas OCI mediante LABEL, y a que Docker vigile por su cuenta el endpoint /salud con HEALTHCHECK para que docker ps muestre healthy o unhealthy. Ese es el salto entre una imagen que arranca y una imagen que puedes poner en producción sin sonrojarte.