Descripción general

El Dockerfile define cómo Docker construye una imagen. Esta chuleta cubre las 17 instrucciones primarias, patrones avanzados como compilaciones multietapa y montajes de caché, mejores prácticas para seguridad y rendimiento, y técnicas de optimización. Toda la sintaxis es actual para Docker 27.

Instrucciones básicas

FROM

Instrucción Propósito Ejemplo
FROM <image>:<tag> Establecer imagen base (debe ser la primera línea, excepto comentarios/ARG) FROM ubuntu:24.04
FROM <image>:<tag> AS <stage> Establecer etapa nombrada en compilación multietapa FROM golang:1.22 AS builder
FROM scratch Comenzar desde base vacía (solo para binarios estáticos) FROM scratch

Notas:
– Puedes usar múltiples declaraciones FROM para crear múltiples etapas de construcción.
– Cada FROM reinicia el sistema de archivos; capas anteriores se descartan a menos que se copien explícitamente.
– scratch contiene solo lo que explícitamente añadas; imagen más pequeña posible.

RUN

Instrucción Propósito Ejemplo
RUN <command> Ejecutar un comando durante la construcción (forma shell) RUN apt-get update && apt-get install -y curl
RUN ["executable", "param1", "param2"] Ejecutar un comando en forma exec (sin shell) RUN ["python3", "-m", "pip", "install", "django"]

Mejores prácticas:
– Usa forma exec cuando sea posible para evitar problemas de interpretación shell.
– Encadena comandos con && para mantener capas pequeñas: RUN apt-get update && apt-get install && apt-get clean
– Limpia caché del gestor de paquetes: rm -rf /var/lib/apt/lists/* (apt), apk del .build-deps (apk)
– Usa banderas --no-cache en gestores de paquetes para reducir tamaño de capa.

COPY

Instrucción Propósito Ejemplo
COPY <source> <dest> Copiar archivos/directorios desde contexto de construcción a imagen COPY app.py /app/app.py
COPY --chown=<user>:<group> <source> <dest> Copiar y establecer propiedad COPY --chown=appuser:appuser . /app/
COPY --chmod=<mode> <source> <dest> Copiar y establecer permisos de archivo COPY --chmod=755 script.sh /app/script.sh

Mejores prácticas:
– COPY es preferido sobre ADD para copia de archivo simple.
– Usa .dockerignore para excluir artefactos de construcción, pruebas, .git.
– Copia solo lo que necesitas; divide en múltiples líneas COPY para eficiencia de caché.

ADD

Instrucción Propósito Ejemplo
ADD <source> <dest> Copiar archivos/directorios, con características extra (extracción tar, recuperación URL) ADD archive.tar.gz /app/
ADD --chown=<user>:<group> <source> <dest> Añadir con propiedad ADD --chown=appuser:appuser file.txt /app/
ADD --chmod=<mode> <source> <dest> Añadir con permisos de archivo ADD --chmod=644 config.txt /etc/config.txt

Notas:
– Si la fuente es un archivo tar/zip/gzip, se extrae automáticamente.
– Si la fuente es una URL, se descarga (sin extracción).
– COPY es usualmente más claro; usa ADD solo para extracción tar o recuperación de URL.

WORKDIR

Instrucción Propósito Ejemplo
WORKDIR <path> Establecer directorio de trabajo para todos los comandos subsecuentes (RUN, CMD, ENTRYPOINT, COPY, ADD) WORKDIR /app

Notas:
– Si el directorio no existe, se crea.
– Usa rutas absolutas para evitar confusión.
– Múltiples instrucciones WORKDIR son acumulativas: WORKDIR /app luego WORKDIR src resulta en /app/src.

ENV

Instrucción Propósito Ejemplo
ENV <key>=<value> Establecer una variable de entorno (disponible en el contenedor en ejecución) ENV NODE_ENV=production
ENV <key> <value> Sintaxis alternativa (deprecada, evitar) ENV DEBUG true

Notas:
– Persiste en contenedores; establecer una vez durante construcción, disponible en tiempo de ejecución.
– Usa para configuración a nivel de aplicación (URLs de base de datos, claves API para pruebas).
– No uses ENV para secretos; usa secretos Docker o pasa en tiempo de ejecución.

ARG

Instrucción Propósito Ejemplo
ARG <name>=<default> Definir una variable en tiempo de construcción (no disponible en contenedor en ejecución) ARG PYTHON_VERSION=3.12
ARG <name> Definir una variable sin predeterminado (debe proporcionarse con --build-arg) ARG BUILD_NUMBER

Uso en construcción:

docker build --build-arg PYTHON_VERSION=3.11 -t myapp:1.0 .

Notas:
– Variables ARG se usan solo durante construcción; no aparecen en imagen final.
– Para pasar valor ARG al contenedor en ejecución, reasignar con ENV: ENV PYTHON_VERSION=$PYTHON_VERSION

EXPOSE

Instrucción Propósito Ejemplo
EXPOSE <port> Documentar que un contenedor escucha en un puerto (no lo publica) EXPOSE 8080
EXPOSE <port>/udp Documentar un puerto UDP EXPOSE 53/udp
EXPOSE <port1> <port2> Documentar múltiples puertos EXPOSE 8080 8443

Notas:
– EXPOSE es solo metadatos; no publica realmente el puerto.
– Para publicar, usa docker run -p <host>:<container> o Docker Compose ports:.
– Útil para documentación y para docker run -P (puertos aleatorios de número alto).

USER

Instrucción Propósito Ejemplo
USER <user> Establecer el usuario (o UID) para RUN, CMD, ENTRYPOINT, COPY, ADD subsecuentes USER appuser
USER <uid>:<gid> Usar UID y GID directamente USER 1000:1000

Mejor práctica para seguridad:

RUN groupadd -r appgroup && useradd -r -g appgroup appuser
USER appuser

Notas:
– Ejecutar como root en un contenedor es un riesgo de seguridad.
– Usa un usuario no root dedicado para limitar radio de explosión en escape de contenedor.
– Debe crearse antes de la instrucción USER (usa RUN).

HEALTHCHECK

Instrucción Propósito Ejemplo
HEALTHCHECK --interval=<seconds> --timeout=<seconds> --start-period=<seconds> --retries=<count> CMD <command> Definir comando de verificación de salud HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 CMD curl -f http://localhost:8000/health \|\| exit 1
HEALTHCHECK NONE Desactivar verificación de salud heredada de imagen base HEALTHCHECK NONE

Opciones:
– --interval: Con qué frecuencia ejecutar la verificación (predeterminado: 30s)
– --timeout: Cuánto tiempo esperar la verificación (predeterminado: 30s)
– --start-period: Período de gracia antes de la primera verificación (predeterminado: 0s)
– --retries: Fallos consecutivos antes de marcar como no saludable (predeterminado: 3)

Notas:
– Código de salida 0 = saludable, 1 = no saludable, 2 = reservado.
– Docker Compose y orquestadores usan estado de salud para reiniciar/reemplazar contenedores.

ENTRYPOINT

Instrucción Propósito Ejemplo
ENTRYPOINT ["executable", "param1"] Definir el proceso principal del contenedor (forma exec, preferida) ENTRYPOINT ["python3", "-u", "app.py"]
ENTRYPOINT command param1 Definir el proceso principal (forma shell, evitar) ENTRYPOINT python3 -u app.py

Forma exec vs. forma shell:
– Forma exec: Ejecuta el ejecutable directamente; señales (SIGTERM) se entregan correctamente; sin interpretación shell.
– Forma shell: Envuelve comando en /bin/sh -c; shell procesa señales, no tu app; puede causar procesos zombis.

Con CMD:

ENTRYPOINT ["python3"]
CMD ["app.py"]
# docker run image arg → python3 app.py arg

Notas:
– ENTRYPOINT define qué no se puede sobrescribir fácilmente.
– Siempre usa forma exec para ENTRYPOINT.

CMD

Instrucción Propósito Ejemplo
CMD ["executable", "param1", "param2"] Proporcionar argumentos o comando predeterminados (forma exec, preferida) CMD ["python3", "app.py"]
CMD command param1 Proporcionar argumentos predeterminados (forma shell, evitar) CMD python3 app.py
CMD ["param1", "param2"] Proporcionar argumentos predeterminados a ENTRYPOINT CMD ["production"]

Notas:
– Si no se establece ENTRYPOINT, CMD es el comando.
– Si se establece ENTRYPOINT, CMD proporciona argumentos a él.
– Siempre usa forma exec para CMD.

VOLUME

Instrucción Propósito Ejemplo
VOLUME <path> Marcar un directorio como punto de montaje de volumen VOLUME /data
VOLUME ["<path1>", "<path2>"] Marcar múltiples puntos de montaje VOLUME ["/var/log", "/data"]

Notas:
– VOLUME es declarativo; documenta que un directorio debe persistirse o montarse.
– No crea realmente un volumen; el volumen se crea en tiempo de ejecución.
– En tiempo de ejecución: docker run -v myvolume:/data image o docker run -v /host/path:/data image

LABEL

Instrucción Propósito Ejemplo
LABEL <key>=<value> Añadir metadatos a una imagen LABEL maintainer="team@example.com"
LABEL <key1>=<value1> <key2>=<value2> Añadir múltiples etiquetas LABEL version="1.0" description="My app"

Notas:
– Las etiquetas se pueden buscar: docker images --filter "label=version=1.0"
– Etiquetas comunes: maintainer, version, description, org.opencontainers.image.*

STOPSIGNAL

Instrucción Propósito Ejemplo
STOPSIGNAL SIGTERM Señal a enviar al detener contenedor (predeterminado: SIGTERM) STOPSIGNAL SIGTERM
STOPSIGNAL SIGKILL Señal de matanza forzada (raramente necesaria) STOPSIGNAL SIGKILL

Notas:
– La mayoría de apps manejan SIGTERM (15) para apagado correcto.
– Usa SIGKILL (9) solo si tu app no maneja SIGTERM.

SHELL

Instrucción Propósito Ejemplo
SHELL ["<executable>", "<param>"] Sobrescribir shell predeterminado (predeterminado: ["/bin/sh", "-c"] en Linux) SHELL ["/bin/bash", "-c"]

Caso de uso:

FROM mcr.microsoft.com/windows/servercore:ltsc2022
SHELL ["powershell", "-Command", "-ErrorActionPreference", "Stop"]
RUN Get-ChildItem

ONBUILD

Instrucción Propósito Ejemplo
ONBUILD <instruction> Disparar una instrucción en imágenes hijo (raramente usado) ONBUILD RUN npm install

Notas:
– Cuando una imagen hijo usa FROM <parent>, las instrucciones ONBUILD del padre se ejecutan.
– Útil para imágenes base que orquestan construcciones; evitar en Dockerfiles de aplicación.

Compilaciones multietapa

Las compilaciones multietapa reducen tamaño final de imagen usando etapas intermedias para construcción y una etapa final solo con dependencias en tiempo de ejecución.

Patrón: Constructor + Tiempo de ejecución

# Etapa 1: Construcción
FROM golang:1.22 AS builder
WORKDIR /src
COPY . .
RUN go build -o app .

# Etapa 2: Tiempo de ejecución (mínima)
FROM alpine:3.20
COPY --from=builder /src/app /app
ENTRYPOINT ["/app"]

Beneficios clave:
– Dependencias de construcción (compiladores, herramientas dev) no están en imagen final.
– Imagen final contiene solo el binario compilado.
– Puede reducir tamaño de imagen de 500MB a 10MB o menos.

Avanzado: Etapas nombradas, construcción condicional

FROM golang:1.22 AS builder
ARG BUILD_TARGET=linux
WORKDIR /src
COPY . .
RUN GOOS=linux GOARCH=amd64 go build -o app .

FROM alpine:3.20 AS runtime
COPY --from=builder /src/app /app
USER nobody
ENTRYPOINT ["/app"]

# Usar: docker build --target runtime -t myapp:latest .

Montajes de caché (Docker 19.03+)

Los montajes de caché preservan archivos entre construcciones, habilitando instalación de paquete más rápida y almacenamiento en caché de dependencias.

FROM python:3.12-alpine
WORKDIR /app

# Montar caché para paquetes pip
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

# Usar: docker build --build-context . -t myapp:1.0 .

Casos de uso:
– Caché del gestor de paquetes (pip, npm, cargo, etc.)
– Caché de artefactos de construcción (caché Go, objetivo Rust, Maven .m2)

Comando de construcción:

docker build -t myapp:1.0 --build-context .

.dockerignore

Usa .dockerignore para excluir archivos del contexto de construcción, reduciendo tamaño de capa y tiempo de construcción.

# .dockerignore
.git
.gitignore
.env
.env.local
*.pyc
__pycache__
.pytest_cache
node_modules
dist
build
*.log
README.md
.vscode
.idea
.DS_Store

Notas:
– Patrones funcionan como .gitignore.
– Reduce tamaño de contexto enviado al demonio Docker.
– Puede acelerar significativamente construcciones en proyectos grandes.

Mejores prácticas para seguridad

Ejecutar como no root

FROM alpine:3.20
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
COPY --chown=appuser:appgroup . /app
USER appuser
ENTRYPOINT ["./app"]

Eliminar capacidades innecesarias

RUN setcap -r /bin/app  # Eliminar todas las capacidades del ejecutable
# O en tiempo de ejecución: docker run --cap-drop=ALL --cap-add=NET_BIND_SERVICE image

Usar sistema de archivos solo lectura

# En tiempo de ejecución: docker run --read-only --tmpfs /tmp image

Imágenes base mínimas

  • alpine:3.20 (~7 MB) — Recomendado para la mayoría de casos
  • distroless/python3-nonroot (~50 MB) — Pre-endurecido, sin gestor de paquetes
  • scratch (~0 MB) — Solo para binarios estáticos

Mejores prácticas para tamaño

Limpiar caché del gestor de paquetes

# Alpine
RUN apk add --no-cache python3 py3-pip

# Debian/Ubuntu
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*

# pip
RUN pip install --no-cache-dir django

Combinar comandos RUN

# Malo (3 capas)
RUN apt-get update
RUN apt-get install -y curl
RUN rm -rf /var/lib/apt/lists/*

# Bueno (1 capa)
RUN apt-get update && \
    apt-get install -y curl && \
    rm -rf /var/lib/apt/lists/*

Usar COPY estratégicamente

# Copiar solo lo que necesitas, en orden de frecuencia de cambio
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY src ./src
# Cambiar src no invalida la capa pip

Patrones que reutilizarás

# Imagen base con ARG para versión
FROM python:${PYTHON_VERSION:-3.12}-alpine AS base

# Multietapa con argumentos de construcción
FROM node:20-alpine AS builder
ARG NODE_ENV=production
RUN npm ci --only=production

# Verificación de salud con curl
HEALTHCHECK --interval=30s --timeout=5s \
  CMD curl -f http://localhost:3000/health || exit 1

# Usuario no root con UID estático para reproducibilidad
RUN adduser -D -u 1000 appuser

# Copiar con propiedad para usuario no root
COPY --chown=appuser:appuser . /app

# Usar caché de construcción para gestores de paquetes
RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt

# Forma exec ENTRYPOINT + CMD
ENTRYPOINT ["python3", "-u"]
CMD ["app.py"]

Preguntas frecuentes

¿Cuál es la diferencia entre COPY y ADD?

COPY es más simple y preferido para archivos locales. ADD puede extraer archivos tar y recuperar URLs, pero estas características pueden causar comportamiento inesperado. Usa COPY a menos que específicamente necesites extracción tar o recuperación de URL.

¿Debo usar ENV o ARG?

ARG es para variables en tiempo de construcción (disponibles solo durante la construcción, no en el contenedor en ejecución). ENV es para variables en tiempo de ejecución (disponibles en el contenedor en ejecución). Usa ARG para configuración de construcción y ENV para configuración de aplicación.

¿Cuál es la diferencia entre ENTRYPOINT y CMD?

ENTRYPOINT define el proceso principal del contenedor y generalmente no se puede sobrescribir. CMD proporciona argumentos predeterminados a ENTRYPOINT, o es el comando si no se establece ENTRYPOINT. Usa forma exec para ambos.

¿Cómo escribo un Dockerfile que construya una imagen pequeña?

Usa una imagen base como alpine:latest o scratch. Usa compilaciones multietapa para copiar solo artefactos compilados. Elimina dependencias de construcción. Limpia caché del gestor de paquetes (rm -rf /var/lib/apt/lists/*). Evita incluir archivos innecesarios (usa .dockerignore).

¿Por qué debo ejecutar como usuario no root?

Ejecutar como root en un contenedor significa que una brecha o escape podría dar acceso root a un atacante del host. Crea un usuario dedicado y elimina capacidades para reducir riesgo. Añade USER <uid> antes del comando final.

Cómo se verificó esta guía

Escrita a mano a partir de la documentación oficial, con cada comando comprobado de nuevo y una segunda revisión antes de publicar. Última revisión: .

Fuentes oficiales consultadas para este artículo

Share.

Los comentarios están cerrados.