El Dockerfile con el que cerraste la lección anterior funciona: construye auroralibros/aurora-api:1.0.0, arranca Express en un contenedor y responde a curl. Pero le faltan las piezas que separan una imagen que funciona de una imagen que puedes poner en producción sin sonrojarte. Ahora mismo, la API se ejecuta como root dentro del contenedor, nadie sabe quién la construyó ni desde qué commit, Docker no tiene forma de saber si el proceso está vivo pero atascado, la versión de Node está escrita a fuego en el FROM, y no puedes ejecutar la imagen con un comando distinto sin perder por completo su comportamiento por defecto. Esta lección resuelve las cinco cosas. Vas a aprender ARG y su diferencia crítica con ENV, el binomio ENTRYPOINT + CMD con sus cuatro combinaciones, USER para dejar de ser root, LABEL con el estándar OCI, HEALTHCHECK contra el endpoint /salud que preparaste en la lección 01-07, y las tres instrucciones menores —VOLUME, STOPSIGNAL, ONBUILD y SHELL— que conviene conocer aunque uses poco. Al final tendrás el Dockerfile profesional de aurora-api.

1. ARG frente a ENV: ámbito y momento
2. ARG antes del primer FROM
3. ENTRYPOINT frente a CMD: las cuatro combinaciones
4. El patrón docker-entrypoint.sh y por qué importa exec "$@"
5. USER: dejar de ejecutar como root
6. LABEL y las etiquetas estándar OCI
7. HEALTHCHECK: que Docker vigile tu servicio
8. VOLUME y por qué declararlo suele ser mala idea
9. STOPSIGNAL y el manejo de señales
10. ONBUILD y SHELL
11. El Dockerfile profesional de aurora-api

Las dos definen variables. La confusión entre ellas es constante, y la diferencia es sencilla de enunciar: ARG existe solo durante la construcción; ENV existe también dentro del contenedor en ejecución.

Un ejemplo que lo demuestra todo. Crea /tmp/arg-env/Dockerfile:

Durante la construcción, las dos están disponibles. Ahora ejecuta:

El ARG está vacío. No es que valga otra cosa: no existe. Se evaporó cuando terminó la build. El ENV sigue ahí.

Y así se pasa un valor desde fuera:

El patrón más útil es combinarlas: un ARG que alimenta un ENV.

Así, --build-arg VERSION_APP=1.2.3 en la construcción acaba siendo una variable de entorno consultable dentro del contenedor. Es como se inyectan números de versión y hashes de commit desde un pipeline de CI (lección 06-02).

Esto hay que grabárselo:

Ahí está la contraseña, en claro, en el historial de la imagen. Cualquiera que descargue la imagen puede leerla con un solo comando, sin arrancar nada. Y publicando en el repositorio público auroralibros/aurora-api, en Internet.

Es la misma regla que arrastras desde la lección 01-07, ahora con una vía de fuga adicional: no solo ENV filtra secretos, también ARG. Para pasar credenciales a una build de forma segura existen los montajes de secretos de BuildKit (RUN --mount=type=secret), que no dejan rastro en ninguna capa; se estudian en la lección 05-05. Para Aurora Libros, la regla se mantiene intacta: las credenciales no entran en la imagen ni al construir ni al ejecutar; se inyectan al arrancar el contenedor.

ARG tiene una peculiaridad de ámbito que sorprende a todo el mundo: un ARG declarado antes del primer FROM solo es visible en las líneas FROM, no dentro de la imagen.

Esa doble declaración (ARG NODE_VERSION sin valor, dentro de la etapa) es la forma de "reimportar" el argumento global. Sin ella, la variable estaría vacía dentro del RUN.

La utilidad práctica es enorme: parametrizar la versión base sin tocar el Dockerfile.

Casos de uso reales para Aurora Libros:

Un aviso: parametrizar la base es cómodo, pero el valor por defecto debe ser el de producción. Si el ARG no tiene valor por defecto y alguien construye sin --build-arg, obtendrá node:-alpine, que no existe, y un error críptico de manifiesto.

CMD, que ya conoces, define qué se ejecuta al arrancar el contenedor y se descarta por completo si pasas un comando en docker run. ENTRYPOINT define un ejecutable que no se descarta: los argumentos de docker run se le añaden detrás.

La combinación de ambas produce cuatro escenarios. Esta tabla es la referencia que conviene tener a mano:

La regla que resume las cuatro filas: ENTRYPOINT es el ejecutable fijo; CMD son los argumentos por defecto, y son lo único que el usuario puede reemplazar.

Compruébalo con la imagen que ya tienes:

El CMD ["node","server.js"] ha desaparecido: el servidor no arranca.

Aquí --version ha sustituido a server.js, pero node sigue estando: se ha ejecutado node --version. El ejecutable es intocable.

Ventajas frente a solo CMD:

• La imagen tiene una identidad clara. Es "la imagen que ejecuta node", no "una imagen genérica".
• Es autodocumentada. docker run tuimagen --help funciona sin más.
• Evita accidentes. Nadie arranca por descuido un contenedor que no hace lo que la imagen promete.

Y su inconveniente principal: depurar cuesta más. Con solo CMD, un docker run --rm -it tuimagen sh te da una shell. Con ENTRYPOINT ["node"], ese comando intenta ejecutar node sh y falla. Para eso está --entrypoint:

--entrypoint sustituye el ejecutable fijo. Ojo con un detalle que despista: --entrypoint acepta un solo valor, y todo lo que venga después del nombre de la imagen se le pasa como argumentos:

Todo lo aprendido en la lección 02-03 sobre CMD aplica igual a ENTRYPOINT, agravado:

Con ENTRYPOINT en forma shell pasan dos cosas malas, no una:

1. El PID 1 es sh y no reenvía SIGTERM: los 10 segundos de espera y el SIGKILL de la lección anterior.
2. CMD se ignora por completo, y los argumentos de docker run también. El ENTRYPOINT en forma shell se traga todo el mecanismo de argumentos.

Con ENTRYPOINT, la forma exec no es una recomendación: es obligatoria.

Cuando el arranque necesita lógica —esperar a una dependencia, generar un fichero de configuración, aplicar migraciones—, el ENTRYPOINT apunta a un script.

Crea ~/aurora-libros/api/docker-entrypoint.sh:

Y el Dockerfile lo incorpora así:

El flujo completo:

Es la parte que hay que entender de verdad.

• "$@" son todos los argumentos recibidos, cada uno entrecomillado por separado. Como el ENTRYPOINT es el script y el CMD es ["node","server.js"], "$@" vale node server.js. Las comillas son imprescindibles: sin ellas, un argumento con espacios se partiría en dos.
• exec es lo esencial. Sin exec, el shell lanza un hijo y se queda esperando: el PID 1 sigue siendo el script, y estás exactamente en el escenario de la forma shell de la lección 02-03 —SIGTERM al script, que no lo reenvía, diez segundos y SIGKILL—. Con exec, el shell se reemplaza a sí mismo por node: mismo PID, mismos descriptores de fichero, el script desaparece del árbol de procesos y node pasa a ser el PID 1.

Compruébalo con el script en marcha:

PID 1 es node, no sh. El script se ejecutó, hizo su trabajo y se apartó. Y por tanto:

Si quitaras el exec, esa cifra sería 10 segundos. Un carácter de diferencia, cuatro letras, y todo el comportamiento de parada del contenedor cambia.

Nota práctica: el script usa nc (netcat), que en node:22-alpine no viene instalado. Habría que añadir RUN apk add --no-cache netcat-openbsd. En la versión final de esta lección se opta por no incluir la espera activa, porque Docker Compose resuelve las dependencias de arranque de forma más limpia con depends_on y condiciones de salud (lección 04-02). El patrón, sin embargo, conviene conocerlo: te lo encontrarás en las imágenes oficiales de PostgreSQL y MySQL, que lo usan justamente así.

Ahora mismo tu API se ejecuta como root dentro del contenedor. Compruébalo:

uid=0 es root. Un contenedor está aislado, pero ese aislamiento no es una muralla infranqueable: si aparece una vulnerabilidad de escape del runtime o montas mal un volumen, el root del contenedor puede convertirse en root del host. Ejecutar como usuario sin privilegios elimina esa clase entera de problemas por un coste de tres líneas.

La instrucción es USER, y afecta a todas las instrucciones posteriores del Dockerfile y al proceso del contenedor:

node:22-alpine ya trae un usuario node (uid 1000), así que bastaría USER node. Pero conviene saber crearlo, porque en otras bases no existe:

Opciones de las herramientas de Alpine (BusyBox), distintas de las de Debian:

En Debian/Ubuntu el equivalente sería groupadd -g 1001 aurora && useradd -u 1001 -g aurora -m -s /bin/sh aurora.

Este es el punto donde falla todo el mundo:

La secuencia correcta es: instalar y copiar como root (que puede escribir donde quiera), asignar la propiedad en la misma operación de copia con --chown, y poner USER justo antes del CMD. Como viste en 02-03, --chown en el COPY evita un RUN chown -R posterior que duplicaría el tamaño de la capa por el copy-on-write.

Comprueba el resultado en la imagen final:

Un usuario sin privilegios no puede escuchar en puertos por debajo del 1024. Si tu aplicación usara el puerto 80, dejaría de arrancar:

Por eso aurora-api escucha en el 3000, y por eso el contenedor de Nginx del módulo 4 requerirá cuidado. La solución nunca es volver a root: es escuchar en un puerto alto y publicarlo donde haga falta con -p 80:3000, ya que el mapeo lo hace Docker en el host, no el proceso.

El endurecimiento completo de la seguridad en ejecución —capabilities, --read-only, no-new-privileges, perfiles seccomp, user namespaces— es la lección 05-03. Aquí te quedas con lo esencial: un contenedor de producción no se ejecuta como root.

LABEL añade metadatos arbitrarios a la imagen en forma de pares clave-valor. No cambia el comportamiento, no pesa nada, y responde a preguntas que en producción son urgentes: ¿de qué commit salió esta imagen? ¿quién la mantiene? ¿de qué versión es?

Agrupa siempre varias etiquetas en una sola instrucción: cada LABEL crea una capa de metadatos.

Para que las herramientas puedan leer estos datos existe un vocabulario estándar, org.opencontainers.image.*, definido por la Open Container Initiative (la misma de la lección 01-03):

Aplicadas a Aurora Libros, combinando ARG para lo que varía en cada build:

Los tres primeros ARG se rellenan en la build, típicamente desde el pipeline:

Y así se leen después:

El valor real de esto se ve a las tres de la mañana de un martes: producción falla, tienes un contenedor corriendo y necesitas saber exactamente qué código lleva dentro. Un docker inspect te da el commit 7a3f912, y con él el git log te cuenta todo. Sin esa etiqueta, empieza la arqueología.

Las etiquetas también sirven para filtrar, con la sintaxis de la lección 01-04:

Un contenedor puede estar Up y ser completamente inútil: el proceso vive pero el bucle de eventos está bloqueado, el pool de conexiones agotado o la aplicación devolviendo 500 a todo. docker ps diría Up 3 hours tan tranquilo. HEALTHCHECK le da a Docker una forma de comprobar la salud real.

El comando determina el estado por su código de salida: 0 = sano, 1 = enfermo. Cualquier otro valor se trata como error.

--start-period merece atención especial. Sin él, una aplicación que tarda 20 segundos en arrancar sería marcada unhealthy durante ese arranque legítimo, y en un orquestador la matarían y reiniciarían en bucle eterno. El periodo de gracia dice: "durante los primeros N segundos, si falla, no lo cuentes".

Aurora Libros ya tiene el endpoint /salud desde la lección 01-07, diseñado precisamente para esto: devuelve 200 si la base de datos y la caché responden, y 503 si no.

Detalles de la elección del comando:

• wget y no curl: node:22-alpine trae wget (de BusyBox) pero no curl. Usar curl obligaría a un apk add curl que añade unos 4 MB. Si prefieres curl, la opción es curl -f http://localhost:3000/salud || exit 1, donde -f hace que devuelva código de error ante un HTTP 4xx/5xx.
• --spider: no descarga el cuerpo, solo comprueba que el recurso responde.
• --tries=1: sin reintentos internos; ya reintenta Docker con --retries.
• || exit 1: normaliza cualquier fallo al código 1, que es lo que Docker espera.
• localhost: la comprobación se ejecuta dentro del contenedor, así que localhost es el propio servicio. No necesita puertos publicados.
• Los tiempos: cada 30 s, con 3 s de paciencia, 10 s de gracia al arrancar y 3 fallos seguidos antes de declararlo enfermo. En el peor caso, un servicio caído se detecta en unos 90 segundos.

Recién arrancado:

health: starting es el periodo de gracia. Espera y vuelve a mirar:

unhealthy, y con razón: /salud devuelve 503 porque no hay PostgreSQL ni Redis, exactamente como en las lecciones anteriores. El healthcheck está haciendo su trabajo con total precisión: el proceso vive, pero el servicio no está operativo. Justo la distinción que Up no sabe hacer.

El historial completo está en los metadatos:

FailingStreak: 3 son los tres fallos consecutivos que dispararon el cambio de estado. El campo Log guarda las últimas comprobaciones con su salida, que es donde miras cuando un healthcheck falla y no sabes por qué.

Los estados posibles:

Y por qué importa más allá de la columna de docker ps:

• Docker Compose puede esperar a que un servicio esté healthy antes de arrancar otro con depends_on: condition: service_healthy (lección 04-02). Es la solución limpia al problema que intentaba resolver a mano el script del apartado 4.
• Docker Swarm reemplaza automáticamente las réplicas unhealthy (lección 06-03).
• Kubernetes tiene su propio mecanismo equivalente, las probes (lección 06-05).

Limpia:

Si tu imagen base define un healthcheck que no te sirve, puedes desactivarlo:

Es raro, pero aparece al heredar de imágenes corporativas con comprobaciones que no aplican a tu caso.

VOLUME declara que un directorio de la imagen debe montarse como volumen:

Cuando arranques un contenedor de esa imagen sin especificar nada, Docker creará automáticamente un volumen anónimo para esa ruta.

Suena útil, y sin embargo la recomendación general es no ponerlo. Cuatro razones:

1. Genera volúmenes anónimos huérfanos. Cada docker run sin -v explícito crea un volumen con nombre aleatorio que no se borra al eliminar el contenedor (salvo docker rm -v). En una máquina de desarrollo se acumulan decenas de gigabytes de volúmenes con nombres como f3a9c2e1b8... que nadie sabe si son importantes. Los verás en docker system df en la lección 02-05.
2. No se puede deshacer. Una vez que una imagen declara VOLUME /datos, quien la usa no puede quitarlo. Le impone una decisión de almacenamiento que quizá no le convenga.
3. Rompe el COPY posterior. Todo lo que escribas en esa ruta después del VOLUME en el Dockerfile se pierde silenciosamente, sin ningún aviso. Es un error desesperante de diagnosticar.
4. Es una decisión de ejecución, no de imagen. Quién monta qué dónde lo decide quien despliega, con -v o con la sección volumes: de Compose.

Demostración del punto 3:

El fichero no está. Se escribió en una capa que el montaje del volumen tapa.

Para Aurora Libros no se usa VOLUME en ningún Dockerfile. La API no guarda estado —lee de PostgreSQL y cachea en Redis—, y la persistencia del catálogo se resuelve montando un volumen al ejecutar el contenedor de aurora-db, que es el tema de la lección 03-06. Curiosamente, la propia imagen oficial de PostgreSQL sí declara VOLUME /var/lib/postgresql/data, y es justo el motivo de que aparezcan volúmenes anónimos huérfanos en cuanto experimentas con ella sin -v.

STOPSIGNAL cambia la señal que Docker envía al PID 1 al ejecutar docker stop:

El comportamiento por defecto ya lo conoces de la lección 02-03: docker stop envía SIGTERM, espera 10 segundos y envía SIGKILL, que no se puede capturar ni ignorar.

El problema es que no todos los programas interpretan SIGTERM igual:

El caso de Nginx es el que afecta a Aurora Libros: el contenedor aurora-web del módulo 4 querrá STOPSIGNAL SIGQUIT para no cortar peticiones a medio servir durante un despliegue.

Para la API, SIGTERM (el valor por defecto) es correcto, pero conviene que server.js lo capture para cerrar limpiamente. El patrón, que se retomará en la lección 06-01:

Fíjate en el temporizador de 8 segundos: es deliberadamente inferior a los 10 de docker stop, para forzar la salida antes de que llegue el SIGKILL. Y recuerda que nada de esto sirve si el CMD está en forma shell: la señal no llegaría nunca al proceso de Node.

Dos instrucciones de uso minoritario que conviene reconocer.

Registra una instrucción que no se ejecuta ahora, sino cuando alguien use esta imagen como base con un FROM.

Quien la use solo escribe:

Y al construir, se disparan automáticamente los tres pasos registrados. Es una plantilla para estandarizar microservicios de una organización.

Por qué se usa poco: la magia oculta. Quien lee ese Dockerfile de una línea no ve lo que va a ocurrir; tiene que ir a inspeccionar la base. Depurar un fallo en un ONBUILD es especialmente frustrante, porque el error señala a un fichero que no contiene la instrucción culpable. Las propias imágenes oficiales de Node retiraron sus variantes onbuild hace años por este motivo. Si necesitas estandarizar, hoy es preferible una plantilla de Dockerfile compartida o un fichero base bien documentado.

Cambia el intérprete que usa la forma shell de RUN, CMD y ENTRYPOINT:

Por defecto es ["/bin/sh", "-c"] en Linux. El caso de uso más común y legítimo en Linux es activar el modo estricto de bash en imágenes con muchos RUN encadenados:

Sin pipefail, ese RUN tiene éxito aunque el curl falle, porque el código de salida de una tubería es el del último comando, y grep sí funcionaría. Con pipefail, el fallo de cualquier eslabón hace fallar la instrucción entera. Es un fallo silencioso clásico que produce imágenes con ficheros vacíos.

Nota para Alpine: node:22-alpine no trae bash, solo ash de BusyBox. Usar SHELL ["/bin/bash", …] allí requeriría RUN apk add --no-cache bash. En el Dockerfile de aurora-api no aparece ningún SHELL: no hay tuberías en los RUN.

Todo junto. Guarda esto en ~/aurora-libros/api/Dockerfile:

Construye la nueva versión:

Verificación completa de todo lo que has añadido:

Fíjate en el detalle: con ENTRYPOINT ["node"], el argumento --eval "..." ha sustituido al CMD ["server.js"] y se ha ejecutado node --eval .... El caso 3 de la tabla del apartado 3, en vivo.

Las tres cosas confirmadas: periodo de gracia, detección correcta de que el servicio no está operativo (falta PostgreSQL, módulo 3) y parada en 0,3 segundos gracias a la forma exec.

Compara con la versión anterior:

Toda esa mejora ha costado cero bytes.

• Usar ARG para secretos. Quedan en docker image history en claro. Para credenciales en la build existen los secretos de BuildKit (lección 05-05); para credenciales en ejecución, -e y ficheros de entorno (lección 04-05).
• Esperar que un ARG global esté disponible dentro de la etapa. Los ARG anteriores al primer FROM solo los ven los FROM. Hay que volver a declararlos, sin valor, dentro de la etapa.
• ENTRYPOINT en forma shell. Rompe dos cosas: el PID 1 pasa a ser sh (10 s de parada) y los argumentos de docker run y el CMD se ignoran por completo. Forma exec siempre.
• Un script de entrypoint sin exec. El script se queda como PID 1, no reenvía SIGTERM y vuelves a los 10 segundos y el SIGKILL. La última línea debe ser exec "$@", con comillas.
• USER demasiado arriba. Si cambias de usuario antes de npm ci, el paso falla con EACCES. Instala como root, copia con --chown y pon USER justo antes del CMD.
• RUN chown -R después de copiar. Duplica el tamaño de esa capa por copy-on-write. Usa COPY --chown.
• Un usuario sin privilegios escuchando en el puerto 80. EACCES: permission denied. Escucha en un puerto alto y publica con -p 80:3000.
• HEALTHCHECK sin --start-period. El contenedor se marca unhealthy durante su arranque legítimo y el orquestador entra en un bucle de reinicios.
• Un healthcheck que consulta dependencias externas y no distingue. Si /salud devuelve 503 porque la base de datos está caída, el orquestador reiniciará la API, que no tiene la culpa de nada. Para Aurora Libros es correcto en desarrollo; en producción conviene separar liveness (¿vive el proceso?) de readiness (¿puede atender?), y eso se ve en la lección 06-05.
• VOLUME en el Dockerfile. Genera volúmenes anónimos huérfanos, no se puede deshacer y hace desaparecer silenciosamente lo que escribas después en esa ruta. Decide el almacenamiento al ejecutar.
• Consejo: pon los LABEL en una sola instrucción, con \ para partir líneas. Cada LABEL es una capa de metadatos.
• Consejo: prueba el comando del healthcheck a mano con docker exec antes de meterlo en el Dockerfile. Ahorra ciclos de build enteros.

Construye una imagen basada en alpine:3.21 que:

1. Reciba un ARG ENTORNO_BUILD con valor por defecto local.
2. Defina un ENV ENTORNO_RUN a partir de ese ARG.
3. Imprima ambos valores durante la construcción con un RUN.
4. Imprima ambos al ejecutar el contenedor.

Después:

• Constrúyela sin --build-arg y ejecútala. ¿Qué imprime cada variable?
• Constrúyela con --build-arg ENTORNO_BUILD=produccion y ejecútala. ¿Qué cambia?
• Ejecuta la imagen con -e ENTORNO_RUN=sobrescrito. ¿Se puede hacer lo mismo con el ARG?
• Comprueba con docker image history si el valor del ARG es visible. Explica qué implica esto para las contraseñas.

Crea cuatro imágenes basadas en alpine:3.21, una por fila de la tabla del apartado 3, usando echo como ejecutable. Para cada una, ejecuta docker run --rm <imagen> y docker run --rm <imagen> adios y anota la salida real. Después:

1. Rellena la tabla con lo observado y compárala con la teórica.
2. Explica en una frase la regla que gobierna las cuatro filas.
3. Usa --entrypoint para ejecutar ls / en la imagen de la cuarta fila.

El HEALTHCHECK actual de aurora-api marca el contenedor unhealthy cuando falla PostgreSQL, aunque la API funcione perfectamente. Diseña una alternativa:

1. Explica por qué eso es problemático en un orquestador que reinicia los contenedores enfermos.
2. Propón dos endpoints distintos y qué debería comprobar cada uno.
3. Escribe el HEALTHCHECK que usarías en el Dockerfile y justifica la elección.
4. Demuestra con un contenedor real la diferencia entre comprobar /salud (que devuelve 503 sin base de datos) y comprobar solo que el puerto responde.

Solución al ejercicio 1

Con --build-arg:

Análisis:

• En build, ambas existen. El ENV toma el valor del ARG: es el patrón puente.
• En ejecución, el ARG está siempre vacío. Nunca llegó al contenedor.
• El ENV conserva el valor congelado en la build.

Sobrescritura en ejecución:

El ENV sí se sobrescribe con -e. El ARG no, porque no existe en ejecución: -e ENTORNO_BUILD=x crearía una variable de entorno nueva sin ninguna relación con el ARG de la build.

El historial:

El valor produccion aparece en claro en la línea del RUN. Si en lugar de produccion hubiera sido superSecreta2026, cualquiera que descargase la imagen la leería con un solo comando y sin arrancar nada. Esa es exactamente la razón de que ARG no sirva para secretos, por mucho que "desaparezca" en ejecución: desaparece del entorno, no del historial.

Solución al ejercicio 2

1. La tabla observada coincide con la teórica. El caso 1 con argumento es especialmente ilustrativo: adios reemplazó al CMD entero y Docker intentó ejecutar un programa llamado adios, que no existe. En el caso 2, adios se añadió al ENTRYPOINT. En el 3 y el 4, adios sustituyó al CMD pero el ENTRYPOINT permaneció.

2. La regla: ENTRYPOINT es el ejecutable fijo y CMD son sus argumentos por defecto; lo que escribes tras el nombre de la imagen en docker run reemplaza únicamente al CMD.

3. Con --entrypoint:

--entrypoint ls sustituye a echo, y el / posterior al nombre de la imagen sustituye al CMD, quedando ls /. Es el comando que necesitarás cada vez que quieras inspeccionar una imagen con ENTRYPOINT propio:

Solución al ejercicio 3

1. El problema. El healthcheck actual comprueba /salud, que devuelve 503 si PostgreSQL o Redis no responden. En Swarm o Kubernetes, un contenedor unhealthy se reinicia o se reemplaza. Si la base de datos cae cinco minutos, todas las réplicas de la API se marcarán enfermas y entrarán en un ciclo de reinicios pese a estar perfectamente sanas. Peor aún: cuando PostgreSQL vuelva, se encontrará con una avalancha de reconexiones de réplicas recién arrancadas, con las cachés vacías. Se ha convertido un fallo de una dependencia en una caída total y en una tormenta de reintentos.

2. Dos endpoints con responsabilidades distintas:

La distinción es la clave: reiniciar arregla un proceso atascado, pero no arregla una base de datos caída. Ante un fallo de dependencia, lo correcto es dejar de enviarle tráfico a esa réplica y esperar, no matarla.

3. El HEALTHCHECK del Dockerfile:

Justificación: el HEALTHCHECK de Docker tiene un único estado, y su consecuencia natural es el reinicio o el reemplazo. Por tanto debe reflejar la liveness. La readiness la consulta el balanceador o el orquestador por su cuenta —en Compose, con depends_on: condition: service_healthy (lección 04-02); en Kubernetes, con una readinessProbe separada (lección 06-05)—.

El endpoint nuevo en server.js sería tan simple como:

4. La demostración. Con el healthcheck actual, sin base de datos:

Ahora sobrescribiendo el healthcheck en tiempo de ejecución para comprobar solo que el puerto responde:

El mismo contenedor, con la misma base de datos ausente, es unhealthy con una comprobación y healthy con la otra. La petición a /libros/abc devuelve un 400 de validación —sin tocar PostgreSQL, porque el identificador no es un entero—, lo que demuestra que Express está vivo y enrutando correctamente. Es exactamente la señal de liveness que se busca.

Fíjate de paso en las opciones --health-* de docker run: permiten sobrescribir el healthcheck de la imagen sin reconstruirla, algo utilísimo para experimentar.

Tu imagen ha pasado de "funciona" a "es profesional", y sin ganar un solo byte. Sabes distinguir ARG de ENV por su ámbito y su momento —el primero se evapora al terminar la build, el segundo viaja dentro del contenedor—, y sabes que ninguno de los dos sirve para secretos, porque un --build-arg con una contraseña queda escrito en claro en docker image history. Has usado ARG antes del FROM para parametrizar la versión de Node y poder probar Node 23 sin editar una línea.

Dominas el binomio ENTRYPOINT + CMD y sus cuatro combinaciones, con la regla que las resume: el ENTRYPOINT es el ejecutable fijo, el CMD son los argumentos reemplazables, y --entrypoint es tu puerta de entrada cuando necesitas depurar. Has visto por qué un script docker-entrypoint.sh debe terminar en exec "$@": sin ese exec, el script se queda como PID 1, no reenvía SIGTERM y vuelves a los diez segundos de espera y el SIGKILL. Con USER node has dejado de ejecutar la API como root —uid=1000 confirmado— instalando primero como root y copiando con --chown para no duplicar capas, y entiendes por qué eso obliga a escuchar en el 3000 y no en el 80.

Con once etiquetas OCI la imagen ya dice quién la hizo, de qué commit sale y cuándo se construyó, que es lo que necesitas a las tres de la mañana. Con HEALTHCHECK Docker vigila el endpoint /salud que preparaste en la lección 01-07, y has visto el ciclo completo starting → unhealthy en docker ps, con el historial de fallos en docker inspect. Y sabes por qué VOLUME en el Dockerfile suele ser mala idea —volúmenes huérfanos, decisión irreversible impuesta al usuario y escrituras posteriores que desaparecen sin aviso—, para qué sirve STOPSIGNAL (Nginx necesita SIGQUIT) y qué hacen ONBUILD y SHELL en los pocos casos en que merecen la pena.

auroralibros/aurora-api:1.1.0 es una imagen que ejecuta como usuario sin privilegios, se identifica, se autodiagnostica y se para limpiamente en 0,3 segundos. Ya sabes construirla; ahora conviene saber administrarla. En la siguiente lección, Gestionando Imágenes Docker, te ocuparás del almacén local: listar y filtrar con plantillas, extraer campos concretos con inspect --format, auditar con history qué capa se comió 80 MB, borrar imágenes con contenedores que las usan, entender de dónde salen esas misteriosas imágenes <none>:<none> que se acumulan build tras build, limpiar con la familia prune sin destruir lo que no debes, diagnosticar el espacio con docker system df y llevarte una imagen a otra máquina sin registro alguno, con docker save y docker load.