Docker COPY 명령어의 동작 원리와 빌드 컨텍스트 이해

Dockerfile에서 COPY는 단순히 파일을 옮기는 명령처럼 보이지만,

실제로는 빌드 컨텍스트를 기준으로 동작하는 구조적 개념입니다.

 

많이 헷갈리는 부분은 이겁니다.

COPY는 Dockerfile 기준이 아니라, docker build를 실행한 위치(빌드 컨텍스트)를 기준으로 경로를 해석합니다.

 

예를 들어 다음과 같은 구조가 있다고 가정해보겠습니다.

project/
├─ docker/
│   └─ Dockerfile
├─ app/
│   └─ main.py

그리고 다음 명령으로 빌드합니다.

docker build -f docker/Dockerfile -t my-app .

여기서 . 은 project/ 폴더입니다.
즉, 빌드 컨텍스트는 project/ 입니다.

 

Dockerfile 안에서 이렇게 작성해도 정상 동작합니다.

COPY app /app

왜냐하면 기준은 docker/ 폴더가 아니라,
docker build 명령을 실행한 위치(project/)이기 때문입니다.

 

이 구조를 비유하면 이렇습니다.

Docker는 “이 폴더 안에 있는 파일만 사용할 수 있다”고 선언받고 빌드를 시작합니다.

그래서 컨텍스트 바깥 파일은 접근 자체가 불가능합니다

COPY ../secret.txt /app

. 이런 코드는 보안상 허용되지 않습니다.

COPY는 Dockerfile 기준이 아니라, docker build 시 지정한 “빌드 컨텍스트” 기준으로 동작합니다.