StackPractices
intermediate Por Mathias Paulenko

Optimización de Multi-Stage Builds en Docker

Reduce el tamaño de imagen y el tiempo de build con multi-stage builds, orden de capas inteligente, cache mounts de BuildKit y un .dockerignore ajustado.

Temas: devops

Visión General

Un Dockerfile multi-stage compila tu app en una etapa llena de toolchain y copia solo los artefactos necesarios a una etapa final mínima. Bien hecho, eso ya recorta imágenes un 80-90 por ciento — un servicio Go baja de ~1.2GB con golang:1.22 a ~15MB sobre scratch. Pero el tamaño es solo la mitad del beneficio: el mismo archivo, ordenado mal, también reconstruye tu capa de dependencias en cada commit. Esta receta cubre las dos mitades — achicar la imagen que se publica y el tiempo que tarda en construirse.

Dockerfiles ejecutables para cada ejemplo en el repositorio complementario. Para el deep dive en bases mínimas sin shell, mira imágenes distroless con multi-stage builds — esta página se queda en el lado de la optimización: orden de capas, cachés y velocidad de build.

Cuándo Usar

  • Tu imagen pasa de ~500MB para una app simple, o docker images te sorprende
  • Compiladores, SDKs o node_modules se publican a producción
  • Los builds de CI tardan minutos porque la instalación de dependencias se repite en cada commit
  • Build y runtime necesitan bases distintas — golang para compilar, scratch o distroless para correr

Cuándo NO Usar

  • Scripts de un archivo y contenedores desechables — una segunda etapa no aporta nada
  • Apps que de verdad necesitan su toolchain en runtime (algunos servicios de compilación, hosts de plugins)
  • Si tu único problema son los fallos de caché en CI, un --mount=type=cache puede bastar sin reestructurar nada

Solución

Multi-stage build para Node.js

# Stage 1: Build
FROM node:20-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

# Stage 2: Producción
FROM node:20-alpine AS production

WORKDIR /app

COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force

COPY --from=builder /app/dist ./dist

USER node

EXPOSE 3000

CMD ["node", "dist/index.js"]

npm ci --omit=dev en la etapa final reinstala solo las dependencias de producción — las devDependencies nunca cruzan el FROM. Podar node_modules en el builder y copiarlo entero parece más corto, pero arrastra las dev deps y rompe la caché de capas de otra forma; reinstalar desde el lockfile es más limpio.

Multi-stage para Python con runtime mínimo

# Stage 1: Build dependencias
FROM python:3.11-slim AS builder

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir --target=/opt/deps -r requirements.txt

# Stage 2: Runtime
FROM gcr.io/distroless/python3-debian12 AS runtime

WORKDIR /app

COPY --from=builder /opt/deps /opt/deps
COPY . .

ENV PYTHONPATH=/opt/deps

USER nonroot:nonroot

EXPOSE 8000

CMD ["-m", "gunicorn", "app:app", "--bind", "0.0.0.0:8000"]

pip install --target=/opt/deps deja los paquetes planos en disco — copiables, sin symlinks. Mejor que el truco habitual de COPY --from=builder /opt/venv: el bin/python de un venv es un symlink a la ruta del intérprete del builder (/usr/local/bin/python3.x), que no existe dentro de distroless, así que el venv copiado no arranca. Un matiz: distroless/python3 sigue experimental y fija una versión concreta del intérprete — empareja el python:3.11-slim del builder con ella, o vuelve a python:3.12-slim como runtime manteniendo el mismo patrón --target.

Multi-stage con scratch para Go

# Stage 1: Build
FROM golang:1.22-alpine AS builder

WORKDIR /build

COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o server .

# Stage 2: Runtime (scratch = imagen vacía)
FROM scratch AS runtime

COPY --from=builder /build/server /server
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

EXPOSE 8080

ENTRYPOINT ["/server"]

scratch es una imagen de cero bytes — lo único en tu contenedor es tu binario. CGO_ENABLED=0 es obligatorio (no hay libc contra la que enlazar), y el bundle de CA tiene que venir con él porque scratch no trae nada, ni certificados. Si eso suena a armar el SO a mano, lo es — static-debian12 es scratch más los pocos archivos que cualquier app real necesita (certs, tzdata, una entrada passwd de nonroot), por eso la mayoría de equipos aterrizan ahí.

Multi-stage con Gradle para Java

# Stage 1: Build
FROM gradle:8.7-jdk21-alpine AS builder

WORKDIR /build

COPY build.gradle settings.gradle ./
COPY src ./src

RUN gradle bootJar --no-daemon

# Stage 2: Runtime
FROM eclipse-temurin:21-jre-alpine AS runtime

WORKDIR /app

COPY --from=builder /build/build/libs/*.jar app.jar

RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser

EXPOSE 8080

ENTRYPOINT ["java", "-jar", "app.jar"]

JRE Alpine no trae ningún usuario de cortesía — USER temurin suena plausible y falla en runtime (“unable to find user”). Crea uno, o quita la línea USER del todo. Y usa ENTRYPOINT en forma exec aquí: el jar dentro de CMD funcionaría, pero ENTRYPOINT declara que el contenedor es el proceso JVM, lo que hace que señales como SIGTERM lleguen a Java correctamente para un apagado limpio.

.dockerignore para un contexto más pequeño

# .dockerignore
node_modules
dist
.git
.gitignore
.env
.env.local
*.md
.vscode
.idea
coverage
.nyc_output
docker-compose*.yml

El contexto es lo que se sube al daemon antes de que corra una sola capa — en un repo con node_modules/ y .git son rutinariamente cientos de MB por build. También protege la caché: un cambio suelto en un archivo ignorado ya no invalida el COPY . ..

Optimización del orden de capas

FROM node:20-alpine AS builder

WORKDIR /app

# Copiar archivos de dependencias primero (cacheado a menos que package.json cambie)
COPY package*.json ./
RUN npm ci

# Copiar fuente (invalida caché solo cuando el código cambia)
COPY . .

RUN npm run build

Docker cachea por capa y tira la caché en la primera instrucción que cambió — todo lo que sigue se reconstruye. Las dependencias cambian a lo sumo semanalmente; el código, varias veces al día. Poner el npm ci caro encima del COPY . . barato hace que un commit de código reutilice la capa de dependencias en lugar de instalar todo de nuevo.

Explicación

Cada FROM abre una imagen limpia, y COPY --from=<etapa> es la única forma de pasar archivos de una a otra. Lo que una etapa no exporta desaparece con ella — el SDK, las cachés, los objetos intermedios. Solo la última etapa termina siendo la imagen tageada.

flowchart diagram: subgraph Builder[

Para interiorizar:

  • Stages nombrados (AS builder, AS runtime) son direcciones — COPY --from=builder y docker build --target test resuelven contra ellos.
  • .dockerignore es contexto, no imagen — acelera las subidas y protege la caché, pero no achica la imagen en sí.
  • npm ci antes que npm install — ci instala exactamente el lockfile y falla si está desincronizado; install puede reescribirlo, y entonces dos builds del mismo commit pueden producir árboles distintos.
  • Usuario non-root — USER node/nonroot/appuser antes del ENTRYPOINT; todo runtime lo necesita, la mayoría no lo incluye.
  • Quita símbolos — -ldflags="-s -w" en Go elimina tablas DWARF/de símbolos (~30% del binario) que nada lee en producción.

Variantes

Multi-stage build para Rust

# Stage 1: Build
FROM rust:1.78 AS builder

WORKDIR /build

COPY Cargo.toml Cargo.lock ./
COPY src ./src

RUN cargo build --release

# Stage 2: Runtime
FROM debian:bookworm-slim AS runtime

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

COPY --from=builder /build/target/release/myapp /usr/local/bin/myapp

USER nobody

EXPOSE 8080

CMD ["myapp"]

Rust enlaza glibc dinámicamente por defecto, así que bookworm-slim (~80MB) es el suelo pragmático — o compila con RUSTFLAGS="-C target-feature=+crt-static" y aterriza en scratch/distroless como el ejemplo de Go.

Cache mounts de BuildKit

# syntax=docker/dockerfile:1.7

FROM node:20-alpine AS builder

WORKDIR /app

COPY package*.json ./
# Montar caché de npm como volumen (persiste entre builds)
RUN --mount=type=cache,target=/root/.npm npm ci

COPY . .
RUN --mount=type=cache,target=/root/.npm npm run build
# Cache mount para pip
FROM python:3.12-slim AS builder

WORKDIR /app
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt
# Cache mount para módulos de Go
FROM golang:1.22-alpine AS builder

WORKDIR /build

COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download

COPY . .
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    CGO_ENABLED=0 go build -ldflags="-s -w" -o server .

Los cache mounts persisten las cachés de los gestores de paquetes en el builder entre builds sin hornearlas en ninguna capa — las descargas de dependencias caen casi a cero en rebuilds. Para velocidad de rebuild en CI nada se le acerca, aunque sí requiere el header # syntax=docker/dockerfile:1.7 y BuildKit — ya el builder por defecto en Docker actual.

Etapa de test para CI

# Stage 1: Dependencias
FROM node:20-alpine AS deps

WORKDIR /app
COPY package*.json ./
RUN npm ci

# Stage 2: Test
FROM deps AS test
COPY . .
RUN npm run lint
RUN npm run test:unit

# Stage 3: Build
FROM deps AS builder
COPY . .
RUN npm run build

# Stage 4: Producción
FROM node:20-alpine AS production

WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=builder /app/dist ./dist

USER node
EXPOSE 3000
CMD ["node", "dist/index.js"]
# Correr solo tests
docker build --target test .

# Build imagen de producción (salta la etapa de test si está cacheada)
docker build --target production -t myapp:latest .

Las etapas solo pagan lo que su cadena de FROM usa: test y deps cuestan tiempo de build pero cero bytes en la imagen final, y --target test te da un job de CI sin publicar nada.

Análisis de tamaño de imagen

# Verificar tamaño de imagen
docker images myapp:latest
# REPOSITORY   TAG       IMAGE ID       CREATED         SIZE
# myapp        latest    abc123         2 minutes ago   148MB

# Analizar tamaños de capas
docker history myapp:latest --no-trunc --format "{{.Size}}\t{{.CreatedBy}}"

# Comparar antes/después
docker images --format "{{.Repository}}:{{.Tag}}\t{{.Size}}" | grep myapp
# Usar dive para análisis detallado de capas
dive myapp:latest
# Muestra cada capa, qué se añadió/removió, y desperdicio potencial

docker history es donde salen las capas sorpresa — un RUN apt-get update suelto que cacheó 40MB de índices, o un paquete de depuración instalado “temporalmente” hace tres meses. dive abre una vista interactiva donde comparas lo que añadió cada capa.

Builds multi-arquitectura

# Dockerfile (igual para todas las plataformas)
FROM --platform=$BUILDPLATFORM node:20-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

FROM --platform=$TARGETPLATFORM node:20-alpine AS production

WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=builder /app/dist ./dist

USER node
EXPOSE 3000
CMD ["node", "dist/index.js"]
# Build para amd64 y arm64
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myapp:latest \
  --push .

$BUILDPLATFORM corre la etapa de compilación en la arquitectura de tu host (rápido, nativo) mientras $TARGETPLATFORM produce imágenes finales por arquitectura — QEMU solo emula los pasos baratos de empaquetado, no el compilador.

Mejores Prácticas

  • Multi-stage para cualquier cosa más allá de un script — compiladores y gestores de paquetes nunca pertenecen a producción.
  • La base más pequeña que funcione: scratch > distroless > alpine > slim > full, en ese orden.
  • Dependencias antes que fuente — COPY package*.json ./ encima de COPY . . deja la capa cara intacta entre commits.
  • npm ci, nunca npm install, en Dockerfiles — árboles reproducibles o un fallo ruidoso.
  • --omit=dev (npm) / --no-dev (pip) para que las devDependencies no se filtren entre etapas.
  • .dockerignore desde el día uno — el bloat de contexto es invisible hasta que los builds se arrastran.
  • USER no root antes del ENTRYPOINT — crea el usuario si el runtime no lo incluye.
  • -ldflags="-s -w" en Go — ~30% gratis quitando info de depuración que nadie lee.
  • Encadena la limpieza del gestor de paquetes en el mismo RUN (apt-get install … && rm -rf /var/lib/apt/lists/*) — cada RUN es una capa, y los archivos borrados siguen pesando en las capas anteriores.
  • Tagea versiones reales — :latest no fija nada y los rollbacks dejan de funcionar.

Errores Comunes

  • Sin .dockerignore — node_modules y .git viajan al daemon en cada build.
  • COPY . . encima de la instalación de dependencias — cualquier commit vuelve a instalar todo.
  • npm install en CI — el drift del lockfile significa que la imagen testeada no es la publicada.
  • Publicar el SDK — COPY --from es cómo los compiladores se quedan en el builder donde pertenecen.
  • Correr como root — especialmente absurdo en bases mínimas donde el arreglo son dos líneas.
  • Borrar archivos en un RUN posterior — las capas son aditivas; rm no achica lo que una capa anterior ya pesa.
  • USER con un nombre que no existe (temurin, app) — créalo primero o el contenedor no arranca.
  • Asumir que --target es solo para tests — también es cómo publicas variantes debug y release desde un solo Dockerfile.

Lecturas Recomendadas

Ver También

Preguntas frecuentes

¿Cuánto pueden reducir los multi-stage builds el tamaño de imagen?

Típicamente 80-90 por ciento en runtimes de lenguaje: apps de Node.js bajan de ~900MB a ~150MB, un servicio Go de ~1.2GB a ~15MB sobre scratch. Mide la tuya con docker images --format "{{.Size}}" — el beneficio depende de cuánto toolchain se colaba en producción.

¿Puedo saltar etapas durante el build?

Sí — docker build --target builder para en esa etapa e ignora el resto. Así obtienes una imagen de tests o un builder depurable sin producir la imagen de producción.

¿Cómo depuro una imagen distroless o scratch?

No existe shell dentro, así que docker exec -it sh no aplica. Opciones: construir una variante :debug (distroless publica una con busybox), meter herramientas con docker cp en el contenedor corriendo, o adjuntar un contenedor de depuración efímero en Kubernetes. Para más, mira imágenes distroless con multi-stage builds.

¿Debo usar Alpine o slim?

Alpine es más pequeña (~5MB) pero corre musl libc — las extensiones C de Python y los addons nativos de Node a veces rompen en ella. Slim es compatible con glibc a ~80MB. Empieza con Alpine y cambia a slim si alguna dependencia nativa se niega a compilar sobre musl.

¿Funcionan los cache mounts sin BuildKit?

No — --mount=type=cache necesita BuildKit y el header # syntax=docker/dockerfile:1.7. BuildKit es el builder por defecto en Docker Engine y Docker Desktop actuales, así que en la mayoría de setups funciona directamente.