Multi-stage builds en Docker con ASP.NET

Contenido del curso

Optimización Avanzada en Docker

Buenas Prácticas en Docker

Instalación y Configuración en Entornos Multiplataforma

Redes Avanzadas y Balanceo de Carga

Automatización de CI/CD

Orquestación

Develop

34
Dev containers en VS Code con Docker
09:54 min

Tomar examen

Cursos Empresas Blog Live Conf Eventos Precios

0:008:56

Multi-stage builds en Docker con ASP.NET

Curso de Docker Avanzado

Clase 3 de 34

Clase 3 / 34

Recursos

Optimizar el tamaño de una imagen en Docker es una de las prácticas más valiosas cuando trabajas con proyectos reales, y la técnica de multi-stage en Dockerfile te permite lograrlo separando la compilación de la imagen final. Aprenderás cómo funciona esta estrategia con un proyecto de ASP.NET, por qué reduce el peso de tu contenedor y cuándo conviene aplicarla.

¿Por qué un Dockerfile sencillo deja de ser suficiente?

Cuando empiezas con Docker, lo natural es buscar archivos cortos y limpios. Dos o tres líneas alcanzan para una app básica de Python: defines la imagen base, creas un directorio de trabajo, instalas dependencias y ejecutas. Y listo.

Pero el escenario cambia cuando el proyecto crece. Una API en ASP.NET, por ejemplo, requiere compilación, publicación y empaquetado. Ahí es donde el Dockerfile que genera Visual Studio por defecto sorprende: 25 líneas y múltiples sentencias from repetidas [3:00].

¿Qué es una imagen base en Docker? Es la imagen sobre la que se construye tu contenedor. Se declara con la sentencia from y define el sistema y las herramientas iniciales disponibles.

Esa repetición de from no es un error. Es la pista de que el archivo está usando multi-stage builds.

¿Qué es la técnica multi-stage en Docker y cómo funciona?

La traducción literal sería etapas múltiples, y describe bien lo que ocurre: el Dockerfile crea varias imágenes intermedias y solo conserva lo necesario en la final. En el ejemplo de Visual Studio para ASP.NET, las etapas son tres.

¿Cuáles son las tres etapas del Dockerfile generado por Visual Studio?

Imagen base con runtime. Queda en espera, sin ejecutar nada todavía.
Imagen de build con SDK. Toma el código fuente, los archivos del proyecto de C# y ejecuta dotnet build para compilar.
Imagen de publicación. Ejecuta dotnet publish y deja únicamente los ensamblados listos para ejecutarse.

Al final, esos ensamblados se copian a la imagen base original. El resultado es una imagen final ligera, sin código fuente ni herramientas de compilación, solo con lo estrictamente necesario para correr la aplicación [5:30].

¿Cómo se simplifica este flujo según la documentación de Microsoft?

La documentación oficial propone una versión más compacta con dos etapas en lugar de tres:

Una primera etapa que restaura y publica la aplicación.
Una segunda etapa que monta esa publicación sobre la imagen de ASP.NET.

Menos líneas, misma lógica y un Dockerfile mucho más legible.

¿Cuándo conviene usar multi-stage builds? Cuando tu proyecto requiere compilación previa (como .NET, Java o Go) y quieres que la imagen final no incluya el SDK ni el código fuente, solo los binarios listos para ejecutar.

¿Cómo construir una imagen multi-stage de ASP.NET paso a paso?

La prueba se hace en VS Code, aunque gracias a Docker no necesitas tener .NET instalado para reproducirla. Estos son los pasos clave del flujo demostrado:

Crear un proyecto Web API con el comando dotnet new llamándolo Multistage.
Añadir un archivo Dockerfile en la misma carpeta del proyecto.
Copiar el contenido del Dockerfile que aparece en la documentación de Microsoft.
Ajustar el nombre del proyecto y de la DLL para que coincidan con Multistage.
Ejecutar docker build -t multistage . desde la terminal.

Durante la compilación, Docker muestra mensajes como stage 1 of 3, 2 of 3 y 3 of 3, confirmando que cada etapa se ejecuta en orden [9:10]. Esa es la señal visible de que el multi-stage está funcionando.

¿Cuánto pesa la imagen final y qué viene después?

Una vez terminada la compilación, la imagen aparece en Docker Desktop. El peso final del ejemplo es 843 MB para una aplicación base de .NET sin modificaciones [10:45]. Es mucho menos de lo que pesaría arrastrando SDK, fuentes y artefactos intermedios, pero todavía hay margen.

Entre las herramientas y conceptos que conviene tener claros para seguir optimizando:

Dockerfile: archivo de instrucciones que define cómo se construye una imagen.
from: sentencia que declara la imagen base de cada etapa.
SDK vs runtime: el SDK contiene herramientas para compilar; el runtime solo lo necesario para ejecutar. La imagen final debe basarse en runtime.
dotnet build y dotnet publish: comandos que compilan y empaquetan la aplicación antes de copiarla a la imagen final.
docker build -t: comando que crea la imagen y le asigna una etiqueta para identificarla.

La base ya está lista. ¿Qué optimizaciones aplicarías tú primero para bajar esos 843 MB? Cuéntame en los comentarios.

Ricardo Enrique Arias Teguedor

Hace 10 meses•editado

Pensé que al trabajar con Python no valdría la pena crear un Dockerfile multi-stages, pero consultando un poco encontré un uso similar y bastante práctico: Instalación de dependencias.

Para ello, creé una API con FastAPI sencilla:

from fastapi import FastAPI

app = FastAPI()


@app.get("/health")
async def health_check():
  return {"status": "ok"}

@app.get("/items/{item_id}")
async def read_item(item_id: int):

  return {"item\_id": item\_id, "message": "Item retrieved"}

Y un archivo de dependencias pyproject.toml (opté por usar uv como gestor de dependencias, pero se puede usar pip igualmente, declarando fastapi y uvicorn\[standard] como dependencias del requirement.txt:

[project]

name = "fastapi-docker-comparison"
version = "0.1.0"
description = "FastAPI Docker build comparison"
requires-python = ">=3.13"
dependencies = ["fastapi", "uvicorn[standard]"]

[tool.uv.extra-build-dependencies]
fastapi-docker-comparison = ["uv.build"]

Luego, probé con un Dockerfile de un solo stage:

# Single-stage build

FROM python:3.13-slim-bookworm AS runtime
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app
COPY . .

RUN uv venv -p python3.13 .venv
RUN uv pip install --no-cache-dir .

EXPOSE 8000

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

El tamaño de la imagen resultante fue de alrededor de 200 megas:

fastapi-single:latest                                   85ecaba9a6da        208MB             0B

Luego, declaré el siguiente Dockerfile, con una etapa de instalación de dependencias y otra donde se ejecuta la API:

# Multi-stage build

# Builder stage
FROM python:3.13-bookworm AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app
COPY . .

RUN uv venv -p python3.13 .venv
RUN . .venv/bin/activate && uv pip install --no-cache-dir .

# Final stage
FROM python:3.13-slim-bookworm AS runtime

WORKDIR /app

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

COPY main.py .
EXPOSE 8000
CMD [".venv/bin/uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Tras construir la imagen, obtuve que la imagen final era de 153 megas:

fastapi-multi:latest                                    ab0f446b33ef        153MB             0B

Por lo que sí, pueden beneficiarse proyectos de lenguajes interpretados en ciertos aspectos como instalación de dependencias.

Yendo más allá de esto, en proyectos multi-lenguaje donde hay un componente de frontend y uno de backend, donde el backend es compilado, y se opta por un monolito o algo similar, el proceso puede verse aún más beneficiado al no copiar toolkits y dependencias no necesarias en la imagen final.

Matías Jara

Hace 6 meses

Que interesante tu análisis, gracias por tu aporte.

Comentarios (16)16 comentarios

Edna Lorenzo

Hace 2 años

Leonardo Caicedo

Hace un año

Daniel Eduardo Rojas Pulido

Juan Camilo Suarez

Amaury Centeno Arias

Bryan Key

Diego Meza

Hace 8 meses

Juan Pablo Pelaez

Hace 9 meses

Cristian Henao

Andres Silva Vega

Marcos Vázquez González

Irving Juárez

Hace 7 meses

Airy Nieves

Santiago Pineda Botero

Mauricio Hurtado

Daniel Guzmán Zavala

Optimización Avanzada en Docker

Optimización avanzada de Docker para cloud native

Docker productivo vs comandos básicos

Multi-stage builds en Docker con ASP.NET

Cómo escanear vulnerabilidades en imágenes Docker

Imágenes distroless: de 840 MB a 52 MB

Imágenes Docker para múltiples arquitecturas

Cómo funciona el caché en Docker builds

De 1.19 GB a 126 MB con Alpine

Qué es el build context en Docker

Docker Hub para compartir imágenes en la nube

Buenas Prácticas en Docker

Cómo reducir capas en Docker

Cómo usar .dockerignore para imágenes más pequeñas

Limpia Docker y recupera gigas con prune

Creando usuarios en Docker sin privilegios root

6 prácticas Docker para imágenes listas para producción

Instalación y Configuración en Entornos Multiplataforma

Publica imágenes Docker en Azure Container Registry

Azure Container Registry hacia Container App

Redes Avanzadas y Balanceo de Carga

Redes en Docker: los 5 modelos explicados

Cómo funcionan los puertos en Docker

Balanceo de carga con NGINX en Docker

Automatización de CI/CD

Optimizar Dockerfile con comandos RUN y scripts

Automatiza Docker con GitHub Actions

Pruebas automáticas de Docker con GitHub Actions

Despliegue automático en Azure con GitHub Actions

Orquestación

Docker Compose: balanceo de cargas automatizado

Estructura y plantilla de Docker Compose YAML

Volúmenes Docker: bind vs nombrados

docker-compose down vs Control C en apagado

Docker Swarm para principiantes paso a paso

Despliegue Docker Swarm con réplicas de Nginx

Costos ocultos de contenedores en la nube

Cómo habilitar Kubernetes en Docker Desktop

Planes y límites de Docker Hub en producción

Develop

Dev containers en VS Code con Docker

Multi-stage builds en Docker con ASP.NET