¿Qué significan los IDs de regla como DL3007?

El prefijo es la **familia**: `DL` para reglas de Dockerfile de hadolint, `SC` para reglas de ShellCheck. El número es el **número de regla** en el catálogo público. `DL3007` es "No uses el tag :latest". `SC2086` es "Entrecomilla variables shell para prevenir division de palabras". Buscar un ID en los repos GitHub de hadolint o ShellCheck da la descripción completa, la justificación y ejemplos.

¿Por qué :latest es específicamente un problema?

Porque **:latest es un blanco móvil**. `FROM node:latest` compila con la versión de Node que estuviera etiquetada como latest en el momento del build. Tres meses después la imagen se recompila (caché CI invalidada, refresco de imagen base, lo que sea) y Node 22 ahora es Node 24 con cambios incompatibles. Fija a una **versión específica** como `node:20.11-alpine`, o mejor, **un digest** como `node:20.11-alpine@sha256:abc...` para reproducibilidad completa. Trade-off: un digest requiere bumps manuales.

apt-get install + cleanup, ¿por qué en un RUN?

Porque **cada instrucción `RUN` es una capa separada**. Capa 1 instala paquetes -> 200 MB. Capa 2 borra `/var/lib/apt/lists` -> 0 MB, pero **la capa 1 sigue entregando los 200 MB**. Las capas Docker son append-only; no puedes quitar contenido en una capa posterior. Así que el patrón es **install + clean en un solo RUN**: `RUN apt-get update && apt-get install -y --no-install-recommends curl=1.2 && rm -rf /var/lib/apt/lists/*`. Los 200 MB nunca entran en una capa.

¿Por qué ADD se considera peor que COPY?

Porque **ADD tiene magia oculta**. Hace tres cosas: copia ficheros locales (como COPY), descarga desde URLs (a veces útil, a menudo inesperado) y auto-extrae tarballs (`ADD foo.tar.gz /app/` lo extrae). La auto-extracción sorprende a la gente. **COPY** hace una cosa predeciblemente. Hadolint dice: usa COPY para ficheros locales (`DL3020`); recurre a ADD solo cuando realmente quieras una descarga URL o extracción de tarball. El arreglo en este linter reescribe `ADD` a `COPY` solo cuando la ruta es local.

CMD forma shell vs forma exec, ¿cuál es la diferencia?

**Forma shell**: `CMD npm run start`. Docker envuelve esto en `/bin/sh -c "npm run start"`. El PID 1 real es la **shell**, no tu app. La shell **no reenvía señales** a su hijo, así que `docker stop` envía SIGTERM a la shell, que a menudo se ignora. El contenedor tarda 10 segundos (el timeout de stop por defecto) en morir. **Forma exec**: `CMD ["npm", "run", "start"]`. Tu app es PID 1 directamente, las señales le llegan. El shutdown gracioso funciona de verdad. Prefiere siempre la forma exec (`DL3025`).

¿Por qué importa correr como root?

Tres razones. **Una**, defensa en profundidad: si hay una vulnerabilidad en tu app, root dentro del contenedor puede romper hacia fuera más rápido (piensa en CVEs en versiones antiguas de runc). **Dos**, los Pod Security Standards de Kubernetes rechazan root por defecto en modo restricted; muchas organizaciones corren con eso. **Tres**, los permisos de fichero son confusos cuando tu app escribe como root y alguien más lee como usuario normal (volume mounts). Añade `USER 65532:65532` (o un usuario nombrado creado con `adduser`) hacia el final del Dockerfile, luego asegúrate de que las rutas en las que tu app escribe son escribibles por ese UID.

¿Para qué sirve HEALTHCHECK?

HEALTHCHECK es un comando que Docker ejecuta periódicamente para preguntar "¿está el contenedor listo?". Salida: `healthy` / `unhealthy`. Docker expone este estado a los **orquestadores**: `docker compose up --wait` espera a healthy; Kubernetes puede usar un mecanismo similar vía probes; Swarm reprograma tareas no sanas. Sin un HEALTHCHECK, el contenedor solo está "corriendo", lo cual no es lo mismo que "listo para aceptar trabajo". Añade uno para servicios de larga duración: `HEALTHCHECK --interval=30s --timeout=5s CMD wget -q --spider http://localhost:3000/health || exit 1`.

¿Por qué molestarse en fijar por digest?

Porque **un tag es una etiqueta, un digest es el contenido**. Incluso `node:20.11-alpine` puede ser **republicado** con un contenido distinto (parche de seguridad, actualización de capa base). La mayoría de las veces el cambio es bienvenido, pero en entornos regulados o por reproducibilidad forense, quieres `node:20.11-alpine@sha256:abc...`. Tras fijar, la única forma de que el contenido de la imagen cambie es si tú bumpeas el digest en el Dockerfile y recompilas. Trade-off: debes recordar actualizar por parches de seguridad (usa tooling automatizado como Renovate).

¿Puede el linter reformatear mi Dockerfile entero?

**Parcialmente.** Las sustituciones simples son automáticas: `MAINTAINER` se convierte en `LABEL maintainer`, `ADD` se convierte en `COPY` cuando la fuente es una ruta local. Los cambios complejos necesitan un humano: fijar versiones requiere escoger la versión correcta, fusionar RUNs requiere entender dependencias, añadir HEALTHCHECK requiere saber qué sondear. Usa el panel "fixed" como punto de partida, luego aplica el resto de sugerencias a mano.

Linter de Dockerfile

Comprueba tu Dockerfile contra hadolint y muestra avisos, errores y mejores prácticas.

LiveFunciona en tu navegador

MuestrasHaz clic para cargar

Dockerfile

Pega el contenido de tu Dockerfile

11 líneas

Errores

Avisos

Info

Problemas

DL3007 · line 1
FROM uses :latest tag (node:latest)
Fix: Pin to an explicit version, e.g. `node:20.11-alpine`, or even better, a digest
CUSTOM_DIGEST · line 1
Image node:latest is not pinned by digest
Fix: For maximal reproducibility, pin to a digest: `image:tag@sha256:...`. Trade-off: harder to update
CUSTOM_USER · line 1
Stage (default) never sets USER, will run as root
Fix: Add `USER 65532:65532` (or a named user) toward the end of the build stage
CUSTOM_HEALTH · line 1
Final stage has no HEALTHCHECK
Fix: Add a `HEALTHCHECK CMD ...` so Docker can mark unhealthy containers and other tooling can wait for ready
DL4000 · line 2
MAINTAINER is deprecated since Docker 1.13
Fix: Replace with `LABEL maintainer="name <email>"`
DL3020 · line 3
ADD is used for a local file, use COPY instead
Fix: COPY is preferred for local files. ADD has surprising behavior (auto-extract, URL fetch)
DL3020 · line 4
ADD is used for a local file, use COPY instead
Fix: COPY is preferred for local files. ADD has surprising behavior (auto-extract, URL fetch)
DL3008 · line 6
apt-get install has unpinned versions: curl, wget, git
Fix: Pin versions: `apt-get install -y package=1.2.3`. Build reproducibility depends on this
DL3015 · line 6
apt-get install without --no-install-recommends
Fix: Add `--no-install-recommends` to skip optional dependencies and shrink the image
DL3009 · line 6
apt-get install without cleanup
Fix: Add `&& rm -rf /var/lib/apt/lists/*` at the end of the RUN to delete cached package lists
DL3047 · line 6
wget without --progress (or -q) emits noisy logs
Fix: Use `wget --progress=dot:giga` or `wget -q` to keep the build log clean
DL4001 · line 6
Both wget and curl are used
Fix: Pick one. Mixing both adds an unnecessary package and a few MB to the image
DL3059 · line 6
Multiple consecutive RUN instructions
Fix: Each RUN is a new layer. Merge with `&&` and `\` line continuations to reduce image size
DL3003 · line 7
RUN cd ... is brittle, use WORKDIR
Fix: Each RUN starts a fresh shell. `cd` does not persist across instructions. Use `WORKDIR /path` instead
DL3059 · line 7
Multiple consecutive RUN instructions
Fix: Each RUN is a new layer. Merge with `&&` and `\` line continuations to reduce image size
DL3000 · line 8
WORKDIR uses a relative path (app)
Fix: Use an absolute path, e.g. `WORKDIR /app`
DL3025 · line 10
CMD should use the JSON array form
Fix: Use the exec form: `CMD ["bin", "arg1", "arg2"]`. The shell form (string) forks a /bin/sh that does not forward signals

Versión corregida en lo posible

Sustituciones simples: MAINTAINER -> LABEL, ADD -> COPY. El resto requiere edición manual

FROM node:latest
LABEL maintainer="team@example.com"
COPY package.json .
COPY package-lock.json .
RUN apt-get update
RUN apt-get install -y curl wget git
RUN cd /app && npm install
WORKDIR app
COPY . .
CMD npm run start

Todas las reglas implementadas

DL3000Use absolute WORKDIR
DL3003Use WORKDIR, not RUN cd ...
DL3007Do not use the :latest tag
DL3008Pin versions in apt-get install
DL3009Delete the apt lists after installing
DL3015Avoid additional packages with --no-install-recommends
DL3018Pin versions in apk add
DL3020Use COPY instead of ADD for local files
DL3025Use JSON array syntax for CMD/ENTRYPOINT
DL3028Pin gem versions
DL3045COPY destination should end with a / when copying to a directory
DL3047wget without --progress emits noisy logs
DL3059Multiple consecutive RUN. Consider merging to reduce layers
DL4000MAINTAINER is deprecated. Use LABEL maintainer instead
DL4001Use either wget or curl, not both
DL4006Set SHELL with -o pipefail before using pipes in RUN
SC2086Quote shell variables to prevent word splitting
CUSTOM_USERContainer runs as root. Set USER to a non-root account
CUSTOM_HEALTHHEALTHCHECK is missing for long-running services
CUSTOM_DIGESTImage is not pinned by digest (@sha256:...) for reproducibility

Qué hace este linter

Un Dockerfile que técnicamente compila no es lo mismo que un Dockerfile que debería entregarse. La imagen puede tener unos cientos de MB de caché apt residual que nadie usa. Puede correr como root sin HEALTHCHECK, así que K8s nunca sabe que el contenedor está roto. Puede usar tags `:latest` que cambian bajo tus pies. Puede usar `ADD` donde `COPY` sería más seguro. Ninguna de estas para el build, pero cada una causa dolor en producción.

Este linter ejecuta reglas estilo hadolint en tu navegador. Pega tu Dockerfile y obtienes una lista por línea de issues con ID de regla, severidad, descripción y una pista de arreglo. Unas 20 reglas del catálogo estándar de hadolint (`DL3000`, `DL3007`, `DL3008`, ...) más unas pocas comprobaciones custom para USER no configurado, HEALTHCHECK ausente e imagen no fijada por digest.

Todo corre client-side. Sin subidas, sin build, sin contacto con el daemon Docker. La salida es el mismo tipo de feedback que obtendrías ejecutando `hadolint Dockerfile` localmente, solo dentro de la pestaña del navegador.

Cómo usarlo

Pega tu Dockerfile en el panel de entrada, o elige una de las muestras arriba para ver el formato de salida.
Lee los contadores de error / warning / info arriba a la derecha. Pulsa cualquier issue para ver el número de línea y la pista de arreglo. Cada issue lleva un ID de regla como `DL3007` que puedes buscar para documentación completa de hadolint.
Warnings comunes que el linter marca: tag `:latest` (`DL3007`), `apt-get install` sin versiones fijas (`DL3008`) y **sin `rm -rf /var/lib/apt/lists/*` (`DL3009`), `MAINTAINER` que está obsoleto (`DL4000`), `ADD` para ficheros locales donde `COPY` es más seguro (`DL3020`), `CMD` en forma shell en vez de forma exec JSON (`DL3025`), `RUN cd ...`** en lugar de `WORKDIR` (`DL3003`).
Comprobaciones de seguridad: el contenedor corre como root cuando no hay `USER` configurado, patrones estilo `privileged: true`, imagen no fijada por digest, `HEALTHCHECK` ausente en el stage final.
Usa el panel "fixed" bajo los issues para ver una reescritura de mejor esfuerzo de los casos simples: `MAINTAINER` se convierte en `LABEL maintainer`, `ADD` se convierte en `COPY` cuando la fuente es local. Los arreglos más complejos (fijar versiones, añadir HEALTHCHECK, partir RUN) necesitan lectura humana.
Pulsa Copiar en el panel "fixed" para coger la versión reescrita, o Copiar en el panel de entrada para poner el original en tu portapapeles.
Cuando el linter dice "todo limpio", tienes un Dockerfile que sigue las buenas prácticas conocidas. Puede haber cosas específicas del proyecto que arreglar (tamaño de imagen, orden de capas para caché de build), pero lo básico está cubierto.

Cuándo es útil

Siete situaciones concretas en las que lintear Dockerfile antes de `docker build` ahorra dolores de cabeza reales:

Revisar el PR de un compañero con un Dockerfile nuevo. El linter da una lista objetiva rápida: fija versiones, quita `:latest`, añade cleanup, añade un usuario no-root. Revisión de código centrada en lógica, no en cada trampa común.
Primera pasada de limpieza de un Dockerfile legacy. Muchos Dockerfiles antiguos usan `MAINTAINER`, `ADD` para ficheros locales, `apt-get install` sin cleanup, y una imagen final el doble de grande de lo que podría ser. El linter resalta las victorias fáciles.
Optimizar el tamaño de imagen. `DL3009` (limpieza de listas apt) y `DL3015` (`--no-install-recommends`) juntos pueden reducir imágenes en 100+ MB. `DL3059` (fusionar RUNs consecutivos) reduce el número de capas, lo cual importa a escala.
Pasada de seguridad. `CUSTOM_USER` marca cada stage que termina corriendo como root. Combinado con `CUSTOM_HEALTH` para el stage final, esto son las comprobaciones mínimas de baseline para hardening antes de entregar.
Fijar versiones para reproducibilidad. `DL3007` (sin `:latest`), `DL3008` (versiones apt), `DL3018` (versiones apk), `DL3028` (versiones gem), `CUSTOM_DIGEST` (imagen por sha256). Juntos hacen los builds deterministas.
Enseñar a juniors qué pilla hadolint. Los IDs de regla mapean 1:1 al catálogo público de hadolint para que cualquiera pueda consultarlos y aprender el razonamiento detrás de cada regla.
Comprobación rápida en el navegador antes de hacer push. `docker build` lleva minutos; el linter es instantáneo. Loop de feedback rápido mientras iteras sobre el Dockerfile.

Preguntas y respuestas

hadolint es el linter de Dockerfile open source estándar escrito en Haskell. Usa ShellCheck por debajo para análisis de comandos shell dentro de `RUN`. Esta herramienta implementa las 20 reglas más comunes con los mismos IDs de regla (para que puedas buscarlas en el catálogo de hadolint), corre íntegramente en el navegador, sin instalación. Para análisis de shell con calidad completa de ShellCheck y 60+ reglas, instala hadolint real localmente y úsalo en CI.

Quizá también te interese

Herramientas relacionadas

Constructor de Docker Compose

Construye docker-compose.yml visualmente: services, networks, volumes, envs y healthchecks.

Validador de YAML de Kubernetes

Valida manifiestos Kubernetes (Deployment, Service, Ingress, ConfigMap...) contra el schema oficial.

Constructor de YAML para GitHub Actions

Construye flujos GitHub Actions visualmente con triggers, jobs, steps y matriz.

Constructor de YAML para GitLab CI

Construye flujos GitLab CI visualmente con stages, jobs, runners, artifacts y reglas.

Generador de .editorconfig

Crea tu archivo .editorconfig visualmente con reglas por extensión y preset por lenguaje.

Generador de snippets de Nginx

Genera snippets Nginx: reverse proxy, redirects, rate limit, gzip, cache, SSL.

FROM node:latest LABEL maintainer="team@example.com" COPY package.json . COPY package-lock.json . RUN apt-get update RUN apt-get install -y curl wget git RUN cd /app && npm install WORKDIR app COPY . . CMD npm run start

Qué hace este linter

Cómo usarlo

Pega tu Dockerfile en el panel de entrada, o elige una de las muestras arriba para ver el formato de salida.

Lee los contadores de error / warning / info arriba a la derecha. Pulsa cualquier issue para ver el número de línea y la pista de arreglo. Cada issue lleva un ID de regla como `DL3007` que puedes buscar para documentación completa de hadolint.

Warnings comunes que el linter marca: tag `:latest` (`DL3007`), `apt-get install` sin versiones fijas (`DL3008`) y **sin `rm -rf /var/lib/apt/lists/*` (`DL3009`), `MAINTAINER` que está obsoleto (`DL4000`), `ADD` para ficheros locales donde `COPY` es más seguro (`DL3020`), `CMD` en forma shell en vez de forma exec JSON (`DL3025`), `RUN cd ...`** en lugar de `WORKDIR` (`DL3003`).

Comprobaciones de seguridad: el contenedor corre como root cuando no hay `USER` configurado, patrones estilo `privileged: true`, imagen no fijada por digest, `HEALTHCHECK` ausente en el stage final.

Usa el panel "fixed" bajo los issues para ver una reescritura de mejor esfuerzo de los casos simples: `MAINTAINER` se convierte en `LABEL maintainer`, `ADD` se convierte en `COPY` cuando la fuente es local. Los arreglos más complejos (fijar versiones, añadir HEALTHCHECK, partir RUN) necesitan lectura humana.

Pulsa Copiar en el panel "fixed" para coger la versión reescrita, o Copiar en el panel de entrada para poner el original en tu portapapeles.

Cuando el linter dice "todo limpio", tienes un Dockerfile que sigue las buenas prácticas conocidas. Puede haber cosas específicas del proyecto que arreglar (tamaño de imagen, orden de capas para caché de build), pero lo básico está cubierto.

Cuándo es útil

Siete situaciones concretas en las que lintear Dockerfile antes de `docker build` ahorra dolores de cabeza reales:

Revisar el PR de un compañero con un Dockerfile nuevo. El linter da una lista objetiva rápida: fija versiones, quita `:latest`, añade cleanup, añade un usuario no-root. Revisión de código centrada en lógica, no en cada trampa común.
Primera pasada de limpieza de un Dockerfile legacy. Muchos Dockerfiles antiguos usan `MAINTAINER`, `ADD` para ficheros locales, `apt-get install` sin cleanup, y una imagen final el doble de grande de lo que podría ser. El linter resalta las victorias fáciles.
Optimizar el tamaño de imagen. `DL3009` (limpieza de listas apt) y `DL3015` (`--no-install-recommends`) juntos pueden reducir imágenes en 100+ MB. `DL3059` (fusionar RUNs consecutivos) reduce el número de capas, lo cual importa a escala.
Pasada de seguridad. `CUSTOM_USER` marca cada stage que termina corriendo como root. Combinado con `CUSTOM_HEALTH` para el stage final, esto son las comprobaciones mínimas de baseline para hardening antes de entregar.
Fijar versiones para reproducibilidad. `DL3007` (sin `:latest`), `DL3008` (versiones apt), `DL3018` (versiones apk), `DL3028` (versiones gem), `CUSTOM_DIGEST` (imagen por sha256). Juntos hacen los builds deterministas.
Enseñar a juniors qué pilla hadolint. Los IDs de regla mapean 1:1 al catálogo público de hadolint para que cualquiera pueda consultarlos y aprender el razonamiento detrás de cada regla.
Comprobación rápida en el navegador antes de hacer push. `docker build` lleva minutos; el linter es instantáneo. Loop de feedback rápido mientras iteras sobre el Dockerfile.

Preguntas y respuestas