Docker
Instrucciones esenciales y construcción declarativa de imágenes.
Un Dockerfile es un programa declarativo que transforma una imagen base y un conjunto de archivos de entrada en una nueva imagen reproducible. No describe un servidor que se configura para siempre: describe un build que debe poder repetirse y producir un artefacto destinado a ser reemplazado.
Dockerfile
+ build context
+ parámetros permitidos
+ builder
→ imageCada instrucción participa en una de dos responsabilidades:
Confundir build con runtime conduce a imágenes que dependen de secretos, red, estado manual o configuración específica de un ambiente.
Sin Dockerfile, una imagen puede construirse mediante comandos ejecutados manualmente dentro de un contenedor y guardados con docker commit. Ese resultado presenta varios problemas:
El Dockerfile convierte la construcción en código revisable:
cambio en source o dependencias
→ modificar archivos versionados
→ ejecutar build
→ probar resultado
→ publicar nueva imageLa fuente de verdad deja de ser un contenedor modificado y pasa a ser el conjunto de inputs del build.
Considera:
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY server.js ./
USER node
CMD ["node", "server.js"]Durante el build:
node:22-slim;/app como directorio de trabajo;npm ci se ejecuta y escribe archivos en una nueva capa;server.js;Durante el runtime:
node;node server.js.RUN npm ci no se repite al iniciar cada contenedor. CMD no ejecuta Node durante el build.
Un Dockerfile no es una lista intercambiable. El orden afecta:
Este patrón desperdicia cache:
COPY . .
RUN npm ciCualquier cambio en source invalida el COPY, por lo que la instalación de dependencias se repite.
Una estructura mejor:
COPY package.json package-lock.json ./
RUN npm ci
COPY . .Ahora cambiar server.js no invalida el paso de dependencias mientras los manifestos permanezcan iguales.
FROM node:22-slimFROM selecciona la imagen base de una etapa. Esa base aporta:
No elijas únicamente por tamaño. Evalúa:
FROM node:22.18.0-slim@sha256:...Fijar el digest evita que la base cambie silenciosamente, pero también significa que las correcciones no llegan hasta actualizarlo y reconstruir. Una política madura combina actualización automatizada, pruebas y revisión del digest.
WORKDIR /appDefine el directorio para instrucciones posteriores y el command de runtime. Si no existe, Docker lo crea.
Es preferible a repetir:
RUN mkdir -p /app
RUN cd /app && ...Cada RUN usa un shell nuevo; un cd de una instrucción no cambia automáticamente el directorio de la siguiente. WORKDIR sí modifica la metadata de la etapa.
Utiliza rutas absolutas para evitar que una base image con WORKDIR inesperado cambie el resultado.
COPY package.json package-lock.json ./
COPY --chown=node:node dist ./distCOPY incorpora archivos desde el build context o desde otra etapa.
Aspectos importantes:
.dockerignore no están disponibles;Para copias normales, prefiere COPY porque expresa una intención más limitada.
ADD tiene funciones adicionales, como extracción automática de ciertos archivos tar locales y soporte de fuentes específicas. Esas capacidades pueden ser útiles, pero también menos evidentes. No uses ADD como sinónimo estilístico de COPY.
RUN apt-get update \
&& apt-get install -y --no-install-recommends ca-certificates curl \
&& rm -rf /var/lib/apt/lists/*RUN ejecuta una operación durante la construcción y registra sus cambios de filesystem.
Instalar un paquete con RUN lo incorpora a la imagen. Ejecutar un daemon con RUN service nginx start solo lo inicia temporalmente dentro del paso de build; no quedará ejecutándose en futuros contenedores.
Con package managers que actualizan índices, combina actualización, instalación y limpieza cuando pertenecen a una misma transacción. Separarlas puede utilizar una cache con índices antiguos o conservar archivos innecesarios en capas previas.
Un comando de build debe terminar con exit code no cero cuando falla. Evita patrones que oculten errores:
RUN npm test || trueEsto produce una imagen aunque las pruebas fallen.
Cada descarga añade una dependencia de disponibilidad y mutabilidad. Fija versiones, valida checksums cuando corresponda y evita descargar “la última release” sin identidad.
ENV NODE_ENV=production \
PORT=3000ENV define valores persistentes en la metadata y disponibles para instrucciones posteriores y contenedores.
Úsalo para defaults no sensibles que realmente pertenecen a la imagen. Un valor de runtime puede sobrescribirse con docker run o Compose.
No guardes secretos:
ENV DATABASE_PASSWORD=super-secretEl valor puede aparecer en metadata, historial, inspección y artefactos derivados.
ARG NODE_VERSION=22
FROM node:${NODE_VERSION}-slimARG define parámetros disponibles durante build. Su alcance depende de dónde se declare y de las etapas.
Diferencias centrales:
| Aspecto | ARG | ENV |
|---|---|---|
| Disponible durante build | Sí, según alcance | Sí desde su declaración |
| Disponible por defecto en runtime | No | Sí |
| Apropiado para secretos | No | No |
| Puede afectar cache | Sí | Sí |
Aunque ARG no quede como variable de runtime, puede aparecer en metadata, logs o contenido producido por el comando. Usa secret mounts para credenciales.
USER nodeDefine el usuario para instrucciones siguientes y para el command final si no se sobrescribe.
Una imagen que termina como root aumenta el impacto de:
Las instalaciones de sistema suelen necesitar root. Después prepara ownership y cambia al usuario final:
FROM node:22-slim
WORKDIR /app
COPY --chown=node:node package.json package-lock.json ./
RUN npm ci --omit=dev
COPY --chown=node:node . .
USER node
CMD ["node", "server.js"]Este ejemplo tiene un matiz: RUN npm ci ocurre antes de USER node, por lo que los archivos pueden quedar como root. Puede ser correcto si solo necesitan lectura, pero debes verificar permisos. Otra opción es cambiar de usuario antes o usar un stage preparado específicamente.
UID y GID explícitos pueden facilitar mounts, aunque deben coordinarse con la plataforma.
EXPOSE 3000Documenta que la aplicación espera utilizar un puerto. No publica el puerto en el host y no obliga a la aplicación a escuchar.
Para que funcione el acceso:
0.0.0.0 dentro del contenedor;VOLUME ["/data"]Declara un punto de mount esperado y puede causar la creación de un volume anónimo en runtime. Su uso dentro de imágenes de aplicación requiere cuidado:
No declares VOLUME pensando que eso crea un backup o almacenamiento compartido.
Estas instrucciones definen el proceso predeterminado y se desarrollan en una nota propia.
ENTRYPOINT ["node"]
CMD ["server.js"]La combinación produce node server.js. Los argumentos de docker run suelen reemplazar CMD; --entrypoint puede reemplazar ENTRYPOINT.
Prefiere la forma exec para preservar señales:
CMD ["node", "server.js"]LABEL org.opencontainers.image.source="https://example.com/repository" \
org.opencontainers.image.revision="$GIT_COMMIT"Añade metadata útil para ownership, source, licencia y trazabilidad. No confíes en labels como almacenamiento de secretos o como prueba criptográfica del origen; cualquiera que construya puede escribirlas.
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
CMD ["node", "healthcheck.js"]Define una comprobación predeterminada de salud. Debe ser:
Incluir curl solo para health puede aumentar superficie. Una pequeña comprobación con el runtime de la aplicación puede ser suficiente.
Un healthcheck no reinicia por sí mismo el contenedor ni garantiza readiness permanente.
Varias instrucciones aceptan dos formas.
RUN ["executable", "arg1"]
CMD ["node", "server.js"]Evita un shell implícito para el command de runtime y conserva límites claros entre argumentos.
RUN echo "$HOME"
CMD node server.jsPermite expansión, pipes y operadores, pero introduce el shell. En CMD, puede convertir al shell en PID 1 e interferir con señales.
Para RUN, la shell form es normal cuando necesitas encadenar operaciones. Usa opciones del shell o scripts robustos cuando un pipe deba propagar fallos.
Una Dockerfile puede ser declarativa y aun así no reproducible.
Fuentes de variación:
apt-get install sin versiones;La reproducibilidad práctica busca poder responder:
No siempre se obtiene byte-for-byte idéntico sin trabajo adicional, pero la variación debe reducirse y documentarse.
# syntax=docker/dockerfile:1
FROM node:22-slim AS runtime
ENV NODE_ENV=production
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
npm ci --omit=dev \
&& npm cache clean --force
COPY --chown=node:node server.js ./
USER node
EXPOSE 3000
CMD ["node", "server.js"]ENV define un default no sensible.npm ci --omit=dev instala exactamente el lockfile para producción.CMD mantiene Node como proceso principal.Puede estar fuera del build context o excluido por .dockerignore.
Puede depender de un archivo o descarga conservada accidentalmente. Prueba builds sin cache de forma controlada en CI, pero no uses --no-cache como solución permanente.
Revisa COPY --chown, permisos, UID/GID y archivos creados por RUN.
Un tag mutable puede resolver a otro digest. Registra el digest resultante y automatiza actualizaciones probadas.
Decide si es estado temporal, cache o dato durable. No vuelvas writable todo el root filesystem por comodidad.
Puede producir imágenes distintas para staging y producción. Separa configuración de runtime del build cuando el código sea el mismo.
Consecuencia: builds lentos por invalidación frecuente.
Corrección: copiar primero manifestos estables.
Consecuencia: índices y archivos temporales permanecen en blobs anteriores.
Corrección: agrupar la transacción o usar multi-stage.
Consecuencia: mayor impacto tras compromiso y problemas de ownership.
Corrección: preparar permisos y terminar con USER no privilegiado.
Consecuencia: exposición en metadata, logs o capas.
Corrección: secret mounts y credenciales efímeras.
Consecuencia: builds diferentes y base difícil de auditar.
Corrección: versión/digest más actualización automatizada.
Consecuencia: contenedores diferentes, startup lento y dependencia de red.
Corrección: instalar durante build y publicar una nueva imagen.
Consecuencia: imagen grande y mayor superficie.
Corrección: multi-stage y dependencias de producción.
docker build --progress=plain -t my-api:test .docker image inspect my-api:test
docker image history --no-trunc my-api:testdocker run --rm my-api:test iddocker run --name api-test my-api:test
docker stop --time 10 api-test
docker inspect api-test --format '{{json .State}}'docker run --rm --read-only --tmpfs /tmp my-api:testRevisa dependencias, SBOM, vulnerabilidades, archivos inesperados y ausencia de secretos antes de publicar.
FROM hereda decisiones de compatibilidad y seguridad.COPY incorpora únicamente contenido del context; RUN registra cambios del build.ARG y ENV no son secret stores.RUN service nginx start no deja nginx activo en futuros contenedores?ARG, ENV y un secret mount?FROM?ADD en lugar de COPY y cómo harías explícita la decisión?Build context y ****.dockerignore, para comprender exactamente qué archivos puede leer el builder y cómo reducir exposición, tiempo e invalidaciones.