Build Context

Qué es el context

El build context es el conjunto de archivos y directorios que Docker envía al daemon de Docker cuando ejecutas el comando docker build. Este concepto es fundamental para entender cómo funciona el proceso de construcción de imágenes y por qué es crucial optimizarlo.

Cuando ejecutas un comando como docker build ., el punto (.) especifica el directorio de contexto. Docker toma todos los archivos y subdirectorios de esta ubicación y los empaqueta para enviarlos al daemon de Docker, que puede estar ejecutándose localmente o en un servidor remoto.

Proceso de envío del contexto

El flujo de trabajo del build context sigue estos pasos:

1. Empaquetado: Docker comprime todos los archivos del directorio especificado en un archivo tar.

2. Transferencia: Este archivo se envía al daemon de Docker a través de la API REST.

3. Extracción: El daemon descomprime el contexto en su sistema de archivos temporal.

4. Construcción: Solo entonces comienza a procesar las instrucciones del Dockerfile.

# Ejemplo básico - el contexto es el directorio actual
docker build -t mi-app .

# El contexto también puede ser una ruta específica
docker build -t mi-app ./mi-proyecto

Limitaciones y restricciones del contexto

Es importante entender que el Dockerfile solo puede acceder a archivos dentro del contexto de build. Esto significa que instrucciones como COPY o ADD no pueden referenciar archivos fuera del directorio de contexto:

# ❌ Esto fallará - archivo fuera del contexto
COPY ../config.json /app/config.json

# ✅ Esto funciona - archivo dentro del contexto  
COPY ./config.json /app/config.json

Tamaño del contexto y rendimiento

El tamaño del contexto afecta directamente al rendimiento del build. Un contexto grande genera varios problemas:

• Transferencia lenta: Más tiempo enviando datos al daemon
• Mayor uso de red: Especialmente problemático en builds remotos
• Consumo de almacenamiento: El daemon debe almacenar temporalmente todo el contexto
• Builds más lentos: El proceso de empaquetado y desempaquetado consume tiempo

Ejemplo práctico de contexto ineficiente

Considera esta estructura de proyecto común en desarrollo web:

mi-proyecto/
├── src/
│   ├── index.js
│   └── components/
├── node_modules/          # ¡Miles de archivos!
├── dist/                  # Archivos compilados
├── .git/                  # Historia del repositorio
├── logs/                  # Archivos de log
├── Dockerfile
└── package.json

Si ejecutas docker build . desde el directorio raíz, Docker enviará todo al daemon, incluyendo:

• node_modules/ (que puede tener 50,000+ archivos)
• .git/ (historia completa del proyecto)
• dist/ y logs/ (archivos temporales)

# Al ejecutar este comando verás la transferencia
docker build -t mi-app .
# Salida típica:
# Sending build context to Docker daemon  245.8MB
# Step 1/5 : FROM node:18-alpine

Optimización básica del contexto

La primera línea de optimización consiste en ubicar estratégicamente el Dockerfile:

# En lugar de construir desde la raíz del proyecto
# Crea un subdirectorio específico para el build
proyecto/
├── docker/
│   ├── Dockerfile
│   └── app/              # Solo archivos necesarios
│       ├── package.json
│       └── src/
└── desarrollo/           # Archivos de desarrollo que no se envían
    ├── node_modules/
    └── .git/

Verificación del contexto enviado

Para identificar qué se está enviando al daemon, observa la primera línea del output de docker build:

docker build -t nginx-custom .
# Sending build context to Docker daemon  156.7kB  ✅ Pequeño y eficiente

docker build -t app-pesada .  
# Sending build context to Docker daemon  1.2GB   ❌ Contexto excesivo

Contexto con URL remotas

Docker también puede usar contextos remotos, donde el contexto se descarga desde una URL:

# Build desde un repositorio Git
docker build https://github.com/usuario/proyecto.git

# Build desde un archivo tar remoto
docker build http://ejemplo.com/contexto.tar.gz

El concepto de contexto se mantiene: Docker descarga y extrae los archivos, creando un contexto temporal para el build.

Mejores prácticas para el contexto

Mantén el contexto mínimo: Solo incluye archivos realmente necesarios para la construcción de la imagen.

Estructura proyectos conscientemente: Organiza directorios pensando en qué necesita cada build.

Monitorea el tamaño: Presta atención al mensaje "Sending build context" para detectar contextos excesivos.

El contexto de build es la base sobre la cual se construye toda imagen Docker. Dominarlo te permitirá crear builds más rápidos y eficientes, especialmente cuando combines este conocimiento con técnicas de exclusión de archivos que veremos en la siguiente sección.

.dockerignore efectivo

El archivo .dockerignore funciona como un filtro que previene el envío de archivos innecesarios al contexto de build. Ubicado en el directorio raíz del contexto, este archivo utiliza patrones similares a .gitignore para especificar qué excluir del empaquetado.

Sintaxis y patrones básicos

La sintaxis de .dockerignore sigue las reglas de coincidencia de rutas de Go, permitiendo patrones flexibles para exclusiones precisas:

# Comentarios comienzan con #
*.tmp
*.log

# Directorios completos
node_modules/
.git/
dist/

# Archivos específicos
README.md
Dockerfile.dev

# Patrones con comodines
**/*.test.js
temp-*

Patrones fundamentales:

• * - Coincide con cualquier secuencia de caracteres (excepto /)
• ** - Coincide con cero o más directorios y subdirectorios
• ? - Coincide con un solo carácter
• ! - Negación (incluir archivos que coinciden con el patrón)

Exclusiones comunes por tecnología

Para proyectos Node.js:

node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.nyc_output
coverage/
.env.local
.env.development.local
.env.test.local
.env.production.local

Para proyectos Java/Maven:

target/
*.class
*.jar
*.war
.mvn/
mvnw
mvnw.cmd

Para proyectos Python:

__pycache__/
*.py[cod]
*$py.class
*.so
.Python
env/
venv/
.pytest_cache/
.coverage

Patrones de exclusión avanzados

Exclusión de archivos de desarrollo:

# Herramientas de desarrollo
.vscode/
.idea/
*.swp
*.swo
*~

# Archivos de configuración local
docker-compose.override.yml
.env.local
config.local.json

# Documentación y testing
docs/
tests/
**/*.test.*
**/*.spec.*

Exclusión de archivos temporales y logs:

# Logs y temporales
logs/
*.log
tmp/
temp/
.cache/

# Archivos del sistema operativo
.DS_Store
Thumbs.db
desktop.ini

Uso de patrones de negación

Los patrones de negación (!) permiten incluir archivos específicos dentro de directorios excluidos:

# Excluir todo el directorio docs
docs/

# Pero incluir archivos específicos
!docs/api.md
!docs/deployment.md

# Excluir archivos de configuración
*.config.js

# Pero mantener la configuración de producción
!webpack.prod.config.js

Ejemplo práctico: aplicación Node.js

Estructura del proyecto:

mi-app/
├── src/
├── public/
├── node_modules/           # ❌ Excluir - muy pesado
├── tests/                  # ❌ Excluir - no necesario en producción
├── docs/                   # ❌ Excluir - documentación
├── .git/                   # ❌ Excluir - control de versiones
├── package.json            # ✅ Incluir - necesario para install
├── package-lock.json       # ✅ Incluir - lock de dependencias
├── Dockerfile              # ❌ Excluir - no necesario dentro de la imagen
└── .dockerignore

Archivo .dockerignore optimizado:

# Dependencias (se instalan en el build)
node_modules/
npm-debug.log*

# Archivos de desarrollo
.git/
.gitignore
README.md
.editorconfig
.eslintrc*
.prettierrc*

# Testing y documentación
tests/
docs/
coverage/
.nyc_output

# Archivos temporales
*.log
*.tmp
.cache/

# Docker files
Dockerfile*
docker-compose*
.dockerignore

# IDE y herramientas
.vscode/
.idea/
*.swp
*.swo

# Variables de entorno locales
.env.local
.env.development

Verificación de exclusiones

Para verificar qué archivos se excluyen, puedes usar este truco con docker build y observar el tamaño del contexto:

# Sin .dockerignore
docker build -t test-sin-ignore .
# Sending build context to Docker daemon  245.8MB

# Con .dockerignore optimizado
docker build -t test-con-ignore .
# Sending build context to Docker daemon  2.1MB

También puedes simular el comportamiento con tar para ver exactamente qué se incluiría:

# Ver archivos que se enviarían (similar a lo que hace Docker)
tar --exclude-from=.dockerignore -czf - . | tar -tv

Casos especiales y limitaciones

Archivos en el directorio raíz: .dockerignore solo afecta al contexto, no puede excluir archivos fuera del directorio de build:

# ❌ Esto no funcionará - archivo fuera del contexto
../config.json

# ✅ Esto sí funciona - archivo dentro del contexto
config.json

Dockerfiles múltiples: Cuando usas -f para especificar un Dockerfile diferente, .dockerignore debe estar en el directorio del contexto, no junto al Dockerfile:

# El .dockerignore debe estar en ./contexto/, no en ./docker/
docker build -f ./docker/Dockerfile ./contexto/

Mejores prácticas para .dockerignore

Mantén coherencia con .gitignore: Muchas exclusiones son comunes entre ambos archivos.

Sé específico: Evita patrones demasiado amplios que puedan excluir archivos necesarios.

Documenta exclusiones complejas: Usa comentarios para explicar patrones no obvios.

Prueba regularmente: Verifica que el tamaño del contexto sea razonable.

# === Dependencias ===
node_modules/
vendor/

# === Archivos de build y temporales ===
dist/
build/
*.log
.cache/

# === Desarrollo y testing ===
.git/
tests/
docs/
*.test.*

# === Configuración local ===
.env.local
docker-compose.override.yml

# === Herramientas de desarrollo ===
.vscode/
.idea/
*.swp

Un .dockerignore bien configurado puede reducir el tiempo de build en un 80% o más, especialmente en proyectos con muchas dependencias. La clave está en entender qué archivos son realmente necesarios para construir tu imagen y excluir todo lo demás de forma sistemática.