El build context en Docker define el área de archivos a la que tu Dockerfile tiene acceso al construir una imagen. Entender este concepto te ayuda a crear imágenes más ligeras, seguras y listas para producción, evitando que archivos innecesarios se cuelen en tu despliegue.
Qué es el build context en Docker
Cuando ejecutas docker build, el motor de Docker no trabaja con todo tu disco: trabaja con un contexto específico que tú le indicas. Ese contexto es la carpeta donde Docker puede leer archivos para construir la imagen.
La pista está en el famoso puntito al final del comando. Ese . no es decoración: le dice a Docker dónde buscar el Dockerfile y qué archivos puede tocar.
¿Qué significa el punto en docker build? Es el indicador de la ubicación del Dockerfile y del build context. Le dice a Docker: trabaja con todo lo que esté en esta carpeta y nada más.
Cómo organizar tu proyecto con Dockerfile fuera del código
En proyectos reales no encontrarás el Dockerfile mezclado con tu código fuente. La práctica habitual es separarlo así:
- Una carpeta raíz del proyecto, por ejemplo
api-node.
- Dentro, una carpeta
src con todo el código.
- En la raíz, junto a
package.json y package.lock, vive el Dockerfile.
Con esa estructura, cuando ejecutas docker build desde la raíz del proyecto usando el punto, Docker tiene acceso a src, a los archivos de Node y al propio Dockerfile. Todo lo que esté dentro de api-node queda dentro de la jurisdicción del build context.
Cómo apuntar a un Dockerfile en otra carpeta
No siempre vas a parado dentro de la carpeta del Dockerfile. A veces tu terminal está un nivel arriba y necesitas señalarle a Docker dónde mirar.
En lugar del punto, puedes pasar la ruta de la carpeta. Por ejemplo, parado en build-context:
bash
docker build -t aplicacion-node ./api-node
Eso le dice a Docker dos cosas a la vez: dónde está el Dockerfile y cuál es la carpeta que define el build context. Si pones solo el punto desde fuera, Docker te responderá que no encuentra el Dockerfile.
¿Para qué sirve apuntar a una carpeta específica en docker build? Sirve para acotar el área de acceso. Solo los archivos dentro de esa carpeta entran al contexto, lo que reduce peso y evita que documentos o assets innecesarios se cuelen en la imagen.
Por qué importa la regla del build context acotado
La regla es simple: todo lo necesario para construir tu imagen debe estar dentro del build context, y todo lo que sobre debería quedarse fuera. Si tienes documentación, imágenes de marketing o archivos de configuración local que no aportan a la imagen, déjalos fuera de la carpeta a la que apunta Docker.
Esto te da tres beneficios concretos:
- Imágenes más ligeras porque no arrastras archivos basura.
- Builds más rápidos porque Docker envía menos información al daemon.
- Menor superficie de ataque al no incluir archivos sensibles por descuido.
Cómo usar EXPOSE sin abrir puertos de más
Dentro del Dockerfile de Node aparece la sentencia EXPOSE, que declara qué puerto de la imagen queda disponible por defecto al publicarla. En este caso, el puerto 3000.
Aquí va una recomendación de seguridad importante: abre solo los puertos estrictamente necesarios. Si tu app usa un único puerto, no expongas tres o cuatro por inercia. Cada puerto abierto es una puerta más por la que un atacante puede intentar entrar.
dockerfile
EXPOSE 3000
Menos puertos expuestos significa una imagen menos vulnerable a ataques externos.
Pasos para construir la imagen Node con build context
Para replicar el flujo de la práctica:
- Crea una carpeta contenedora, por ejemplo
build-context.
- Dentro, coloca tu carpeta de proyecto
api-node con su src, package.json y el Dockerfile.
- Muévete con
cd build-context a la carpeta padre.
- Ejecuta
docker build -t aplicacion-node ./api-node para apuntar al Dockerfile y delimitar el contexto.
- Verifica que la imagen se haya creado y revisa su tamaño.
Un detalle práctico: los nombres de imágenes en Docker deben ir en lowercase. Si usas mayúsculas, el comando fallará y tendrás que corregirlo antes de seguir.
Cómo reducir el tamaño de tu imagen Docker desde el contexto
Delimitar bien el build context es una de las palancas más directas para reducir peso. Si tu carpeta de proyecto tiene PDFs, capturas, datasets de prueba o carpetas de documentación, sácalas del contexto antes de construir.
La imagen resultante de la API de Node sigue siendo grande y necesita refactor adicional con imágenes base más ligeras, pero el primer paso siempre es el mismo: llevar a la imagen lo estrictamente necesario. Cada archivo que evitas incluir es espacio que ahorras en el registry, en el pull y en el despliegue.
¿Cómo organizas tú las carpetas de tus proyectos cuando trabajas con Docker? Cuéntame en los comentarios qué estructura te ha funcionado mejor.
