Instrucción RUN Dockerfile

La instrucción RUN de Dockerfile ejecuta comandos durante la construcción de una imagen. Se utiliza para instalar dependencias y preparar archivos o directorios; los cambios que deja en el sistema de archivos se incorporan a una capa de la imagen. No arranca la aplicación cuando se crea el contenedor: esa función corresponde a CMD o ENTRYPOINT.

👉 Y recuerda, si quieres aprender más de Linux, visita el curso de Linux gratis.

🐳 Si quieres aprender más de Docker, visita el curso de Docker gratis.

Qué hace RUN durante la construcción

Docker procesa las instrucciones RUN en orden al construir la imagen. Cada instrucción crea una capa con los cambios que produjo el comando. Si el comando falla, la construcción se detiene; si el build posterior puede reutilizar la caché de esa instrucción y sus entradas no han cambiado, Docker puede omitir su ejecución.

Por eso conviene que un RUN tenga un propósito claro y que las operaciones relacionadas permanezcan juntas. En sistemas Debian y Ubuntu, por ejemplo, se suele ejecutar la actualización de índices y la instalación de paquetes dentro del mismo RUN: así se evita reutilizar una lista de paquetes antigua de una capa anterior.

Sintaxis de RUN en Dockerfile

RUN admite dos formas. La forma shell ejecuta el comando mediante el shell de la imagen base; la forma exec recibe un array JSON con el ejecutable y sus argumentos. La forma shell es habitual para encadenar operaciones con operadores como &&. La forma exec evita depender de la interpretación implícita del shell.

FROM debian:bookworm-slim

RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates curl \
    && rm -rf /var/lib/apt/lists/*

RUN ["mkdir", "-p", "/opt/app"]

FROM debian:bookworm-slim

RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates curl \
    && rm -rf /var/lib/apt/lists/*

RUN ["mkdir", "-p", "/opt/app"]

En el primer RUN, && hace que cada paso se ejecute solo si el anterior termina correctamente. Instalar los paquetes y borrar los índices de apt en la misma instrucción evita conservar esos archivos en otra capa. El segundo RUN muestra la forma exec; al no iniciar un shell, no interpreta expansiones de variables ni operadores de shell.

Elegir entre forma shell y forma exec

Buenas prácticas al escribir RUN

• Combina operaciones que dependen entre sí: en especial, actualizar e instalar paquetes con el mismo gestor.
• Limpia archivos temporales en la misma instrucción: borrar una caché en un RUN posterior no elimina los bytes que ya quedaron en una capa anterior.
• Instala solo lo que la aplicación necesita: las herramientas de diagnóstico o compilación pueden pertenecer a una etapa de build separada.
• Revisa el código remoto antes de ejecutarlo: evita descargar y ejecutar scripts sin validar su origen, versión e integridad.
• No incluyas secretos: los comandos y las capas pueden quedar en el historial del build o en su caché.

Errores frecuentes con RUN

• Usar RUN para iniciar un servicio que debería arrancar con el contenedor.
• Separar apt-get update de la instalación y obtener dependencias obsoletas desde la caché.
• Limpiar archivos en una instrucción posterior y esperar que la imagen pese menos; las capas anteriores siguen formando parte de la imagen.
• Usar la forma exec esperando que el shell procese &&, redirecciones o variables.
• Guardar contraseñas o tokens en los argumentos del comando.

Lecciones relacionadas del curso

• Instrucción FROM
• Instrucción COPY
• Instrucción CMD
• Instrucción ENTRYPOINT
• Cómo funciona la caché de construcción

Documentación oficial

• Referencia oficial de RUN
• Buenas prácticas para crear imágenes
• Caché de construcción de Docker