Docker
Archivos enviados al builder, exclusiones y reducción de riesgo y tiempo.
El build context es el conjunto de archivos, directorios y metadata que el builder puede utilizar como entrada para una construcción. La ruta al final de no es un detalle decorativo:
docker builddocker build -t my-api .El punto indica que el directorio actual es el contexto. Las instrucciones COPY y ADD no pueden leer arbitrariamente cualquier archivo del equipo; trabajan dentro de esa frontera y respetan las exclusiones definidas.
filesystem del desarrollador
↓ selección
build context
↓ .dockerignore
contexto efectivo
↓ Dockerfile / BuildKit
image resultanteControlar el contexto mejora velocidad, seguridad, cache y claridad. Un Dockerfile correcto con un contexto descuidado puede enviar credenciales, dependencias, outputs y gigabytes innecesarios al builder.
El builder puede ejecutarse:
Por eso no puede asumir acceso libre al filesystem desde el que se invocó la CLI. Necesita una entrada explícita y transportable.
El contexto define:
Sin esa frontera, un Dockerfile podría depender accidentalmente de archivos personales, paths absolutos o estado local imposible de reproducir en CI.
Supón este proyecto:
project/
├── Dockerfile
├── .dockerignore
├── package.json
├── package-lock.json
├── src/
├── node_modules/
├── .git/
├── .env
├── coverage/
└── dist/Si ejecutas:
docker build projectproject es el contexto. Antes de que COPY pueda consumirlo, .dockerignore excluye paths.
contexto original
├── package.json incluido
├── package-lock.json incluido
├── src/ incluido
├── node_modules/ excluido
├── .git/ excluido
├── .env excluido
└── coverage/ excluidoEl Dockerfile puede copiar src/, pero no puede recuperar .env después de que fue excluido.
docker build .El Dockerfile predeterminado se busca en el contexto, normalmente como Dockerfile.
docker build -f docker/Dockerfile .El Dockerfile está en docker/, pero el contexto continúa siendo .. Las rutas de COPY se interpretan respecto al contexto, no respecto a la ubicación del Dockerfile.
Esto suele confundirse:
COPY ../package.json ./No permite escapar del contexto. Debes elegir un contexto que contenga el archivo o reorganizar la construcción.
docker build -f services/api/Dockerfile .En un monorepo, el root puede servir como contexto para acceder a paquetes compartidos. Sin embargo, implica que todo el repository puede participar como input salvo exclusión.
El archivo .dockerignore utiliza patrones para eliminar contenido del contexto antes de enviarlo o presentarlo al builder.
Ejemplo para Node.js:
.git
.gitignore
.env
.env.*
!.env.example
node_modules
coverage
.next
out
dist
*.log
Dockerfile*
docker-compose*.ymlNo copies esta lista ciegamente. Por ejemplo, excluir dist es correcto si compilas dentro de la imagen, pero incorrecto si el pipeline construye dist previamente y la imagen debe copiarlo.
node_modulesEvita enviar dependencias del host.
*.log**/coverage.env*
!.env.exampleEl orden importa: una regla posterior puede negar una exclusión anterior cuando los directorios padres permiten alcanzar el archivo.
Los detalles de matching deben verificarse con la documentación y versión utilizada. No asumas que funciona exactamente como .gitignore en todos los casos.
Copiar node_modules desde el host puede introducir:
La imagen debe instalar dependencias usando el package manager y lockfile dentro del entorno de build compatible.
El historial puede ser grande y contener información que no pertenece al runtime:
A veces un build necesita el commit para labels o versionado. No es necesario copiar todo .git. CI puede pasar un valor no sensible:
docker build --build-arg GIT_COMMIT="$GITHUB_SHA" .Luego puede guardarse como label. Recuerda que ARG no es apropiado para secretos.
Un error común es pensar que un secreto es seguro porque ninguna instrucción dice COPY .env.
Si .env forma parte del contexto:
COPY . . lo incorpora accidentalmente.La defensa correcta comienza excluyendo el secreto del contexto. Después utiliza mecanismos explícitos como secret mounts.
secreto fuera del contexto
+ transmisión temporal autorizada
+ comando que no lo persiste
→ menor exposición.dockerignore no reemplaza un secret manager, pero reduce una frontera de riesgo.
Las instrucciones COPY calculan cache a partir del contenido y metadata relevante de sus inputs. Un contexto amplio no siempre invalida todo por sí mismo, pero COPY . . convierte muchos archivos en dependencias del paso.
Ejemplo frágil:
COPY . .
RUN npm ciCambiar README, cobertura o un log puede invalidar instalación.
Ejemplo enfocado:
COPY package.json package-lock.json ./
RUN npm ci
COPY src ./srcAhora cada instrucción declara inputs más pequeños. .dockerignore elimina ruido antes de que llegue al grafo.
En builders remotos o Docker Desktop, el contexto puede cruzar procesos, sockets, VM o red.
Síntomas de un contexto excesivo:
Diagnóstico:
docker build --progress=plain .Observa la fase de carga del contexto. También mide el directorio local y revisa archivos grandes:
du -sh .
find . -type f -size +20M -printEl tamaño del proyecto no equivale exactamente al contexto efectivo, pero ayuda a localizar candidatos.
Un monorepo presenta una tensión:
services/api es pequeño, pero no alcanza paquetes compartidos fuera;docker build -f services/api/Dockerfile .Dockerfile:
COPY package.json package-lock.json ./
COPY packages/shared ./packages/shared
COPY services/api ./services/apiVentaja: acceso explícito a dependencias compartidas.
Coste: .dockerignore debe diseñarse para todo el monorepo.
El pipeline genera un directorio con únicamente manifests, source y paquetes requeridos. Aporta control, pero introduce un paso adicional que también debe ser reproducible.
BuildKit permite suministrar contextos adicionales:
docker build \
--build-context shared=./packages/shared \
-f services/api/Dockerfile \
services/apiEl Dockerfile puede consumir el contexto nombrado según las capacidades del frontend. Esto separa fronteras, aunque aumenta complejidad y requiere tooling moderno.
La decisión debe optimizar comprensión y cache, no solo hacer que COPY deje de fallar.
Docker puede construir desde fuentes remotas, como un repository Git o URL soportada.
docker build https://github.com/example/project.git#<commit>Ventajas:
Riesgos:
Fija commits, no branches móviles, cuando necesites reproducibilidad. Usa SSH o secret mounts soportados para acceso privado, nunca keys copiadas al Dockerfile.
Puede construirse con un Dockerfile que no necesita archivos locales:
printf 'FROM alpine:3.22\nCMD ["echo", "hola"]\n' | docker build -Aquí no existe un contexto de archivos tradicional. COPY de contenido local fallará.
Este patrón es útil para imágenes mínimas generadas, pero limita inputs y puede dificultar mantenimiento si se abusa.
Flujos modernos pueden usar archivos de ignore asociados a Dockerfiles específicos, según las capacidades y convenciones soportadas, para diferenciar un build de desarrollo, lint o producción.
Ejemplo conceptual:
Dockerfile
Dockerfile.dockerignore
Dockerfile.test
Dockerfile.test.dockerignoreEsto evita que una única lista global intente servir a builds con inputs distintos. Verifica el naming y soporte exactos de la versión utilizada.
Proyecto:
api/
├── Dockerfile
├── .dockerignore
├── package.json
├── package-lock.json
├── src/
├── test/
├── coverage/
├── node_modules/
├── .env
└── README.md.dockerignore:
node_modules
coverage
.env
.git
*.logDockerfile:
FROM node:22-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY src ./src
COPY test ./test
RUN npm test
FROM node:22-slim AS runtime
ENV NODE_ENV=production
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci --omit=dev
COPY --from=build /app/src ./src
USER node
CMD ["node", "src/server.js"]test, cobertura ni dependencias de desarrollo.COPY porque no se consume.dist;El builder puede necesitar leerlo para la construcción aunque no quede disponible para copiar dentro de la imagen. No dependas de copiar Dockerfile al runtime.
COPY falla o la aplicación queda incompleta. Revisa patrones y excepciones, no elimines .dockerignore por completo.
Un symlink dentro del contexto no debe utilizarse como mecanismo para escapar y copiar contenido arbitrario exterior. Verifica cómo el builder resuelve y valida enlaces.
Un build puede funcionar en un filesystem case-insensitive y fallar en Linux. COPY Config.json no equivale a config.json en todos los hosts.
El contexto representa los inputs capturados por la operación. No diseñes un proceso donde otro comando modifica archivos concurrentemente esperando resultados deterministas.
Un .env no versionado o output local no estará disponible. Eso es normalmente positivo para reproducibilidad, pero debe ser comprendido.
docker build -f project/Dockerfile ~Consecuencia: transferencia masiva y exposición de archivos personales.
Corrección: elegir la frontera mínima que contiene inputs legítimos.
Consecuencia: secretos, caches y dependencias del host en la imagen.
Corrección: excluir y preferir copias dirigidas.
Consecuencia: incompatibilidad de plataforma y build no determinista.
Corrección: instalar desde lockfile dentro del build.
Consecuencia: reglas difíciles de mantener y builds que fallan silenciosamente al cambiar estructura.
Corrección: patrones simples, pruebas de build limpio y documentación de excepciones.
Consecuencia: cache y seguridad deficientes.
Corrección: copiar workspaces concretos, usar named contexts o preparar inputs.
Consecuencia: pueden incorporarse a capas o quedar disponibles al builder.
Corrección: secret/SSH mounts y rotación si hubo exposición.
docker build --progress=plain --no-cache -t context-test .Un build sin cache sirve como prueba ocasional de independencia, no como configuración permanente.
Crea temporalmente un archivo con un nombre sensible y confirma que no aparece en el contexto consumido ni en la imagen. No uses credenciales reales para la prueba.
docker run --rm context-test find /app -maxdepth 3 -type fPara una revisión más profunda, exporta o usa herramientas de análisis de capas en un entorno controlado.
Modifica README, luego source y después lockfile. Observa qué pasos se invalidan. El patrón correcto debe reflejar la dependencia real de cada instrucción.
COPY es relativa al contexto, no al Dockerfile..dockerignore reduce transferencia, exposición e invalidación.COPY . . hacen builds frágiles.COPY ../package.json no debe escapar del context?.dockerignore para una API Node y justifica cada patrón..env nunca aparezca en una instrucción COPY explícita?CMD, ENTRYPOINT y señales, donde se define cómo los defaults de la imagen terminan convirtiéndose en el proceso principal del contenedor.