Instrucción COPY

La instrucción COPY de Dockerfile incorpora archivos o directorios en el sistema de archivos de una imagen. Se usa para añadir el código, las dependencias o los artefactos que una etapa necesita, y su resultado forma parte de las capas de la imagen.

Para usarla correctamente hay que distinguir el contexto de construcción del destino dentro de la imagen. Una ruta de origen normal se resuelve desde la raíz del contexto enviado a Docker; no permite copiar cualquier archivo del equipo anfitrión.

👉 Y recuerda, si quieres aprender más de Linux, visita el curso de Linux gratis.

🐳 Si quieres aprender más de Docker, visita el curso de Docker gratis.

Qué hace COPY en Dockerfile

COPY toma uno o varios orígenes y los coloca en un destino de la etapa actual. El origen suele ser un archivo del contexto de construcción, pero la opción –from permite copiar desde otra etapa, una imagen o un contexto con nombre. Esto resulta especialmente útil en un build multi-stage: compilas en una etapa y copias al runtime solo los archivos finales.

Si el origen es un directorio, Docker copia su contenido y conserva la estructura interna. El destino puede ser absoluto o relativo a WORKDIR. La barra final del destino importa cuando copias un archivo: una ruta de destino que termina en / indica que el archivo debe quedar dentro de ese directorio.

Sintaxis y opciones habituales de COPY

Cuando hay varios orígenes, el último argumento debe ser un directorio de destino. Para nombres con espacios existe la forma JSON de la instrucción. Antes de copiar una ruta, confirma que pertenece al contexto; intentar subir directorios con ../ no permite escapar de su raíz.

Ejemplo: separar dependencias y código para conservar la caché

En este ejemplo, los manifiestos se copian antes del código. Si cambia un archivo de la aplicación pero el archivo de dependencias permanece igual, Docker puede reutilizar la capa de instalación. La segunda etapa recibe únicamente los archivos generados por el build.

FROM node:22-bookworm-slim AS build
WORKDIR /app

# Copia primero los archivos que controlan las dependencias
COPY package.json package-lock.json ./
RUN npm ci

# El código fuente cambia con más frecuencia
COPY src/ ./src/
RUN npm run build

FROM nginx:stable-alpine
COPY --from=build /app/dist/ /usr/share/nginx/html/

El ejemplo supone un proyecto Node con package.json, package-lock.json, una carpeta src y una orden npm run build que genera dist. Ajusta los nombres de archivos y el servidor estático al proyecto real. La ruta después de –from se resuelve desde la raíz del sistema de archivos de esa etapa.

COPY –from y las etapas de construcción

Una etapa se identifica con un alias en FROM y se referencia después con COPY –from. El destino se escribe en la etapa actual; el origen se busca dentro de la etapa indicada. La etapa final no hereda automáticamente todos los archivos de las anteriores: solo recibe lo que declares copiar.

También puedes copiar desde una imagen externa si necesitas un archivo concreto que ya existe en ella. Revisa el nombre y la versión de esa imagen, y evita traer al runtime herramientas o contenido que la aplicación no necesita.

Controla el contexto antes de copiar

El contexto es el conjunto de archivos que Docker pone a disposición de la construcción. Si contiene repositorios, dependencias locales, configuraciones de desarrollo o secretos, esos archivos pueden aumentar la transferencia o entrar accidentalmente en la imagen si se copian de forma amplia. Mantén un .dockerignore junto al Dockerfile y enumera los archivos que no deben formar parte del contexto.

.git
.env
.env.*
!.env.example
node_modules
coverage
*.pem
*.key

Adapta las exclusiones al proyecto. No excluyas archivos necesarios para compilar o ejecutar la aplicación. Si hay una excepción segura que deba permanecer, usa una regla explícita después de excluir el patrón general.

Errores comunes al utilizar COPY

• Copiar todo al principio: cualquier cambio puede invalidar la capa y las operaciones posteriores. Copia primero los archivos que cambian menos y después el código.
• Olvidar .dockerignore: reduce el contexto y evita que archivos locales o secretos se envíen al builder.
• Usar una ruta que no pertenece al contexto: el origen normal no puede acceder a archivos arbitrarios del host.
• Copiar una etapa equivocada: comprueba el alias y la ruta dentro de la etapa origen antes de usar –from.
• Copiar herramientas de build al runtime: en un multi-stage, transfiere solo el artefacto y los recursos que la aplicación necesita.

Lecciones relacionadas del curso

• Qué es .dockerignore: define qué archivos quedan fuera del contexto y de las copias accidentales.
• Cómo reducir el contexto de construcción: limita los archivos enviados al builder.
• Cómo separar dependencias del código: ordena el Dockerfile para aprovechar la caché.
• Qué es un multi-stage build: entiende cómo copiar solo los artefactos necesarios al runtime.

Documentación oficial y recursos

• Docker Docs: instrucción COPY.
• Docker Docs: buenas prácticas de construcción.
• Docker Docs: contexto de construcción.

COPY es más predecible cuando el contexto está reducido, el orden conserva la caché y cada etapa recibe solo los archivos que necesita. Revisa el origen y el destino de cada instrucción para saber exactamente qué terminará dentro de la imagen.