Quick Reference
# .dockerignore
node_modules
.git
dist
.env
*.log
coverage
.DS_Storebuild context는 Dockerfile이 COPY·ADD로 접근할 수 있는 입력 집합입니다. .dockerignore는 이 입력과 원격 builder로 보내는 데이터를 줄입니다. 제외 규칙은 순서가 있으며, 같은 파일에 여러 규칙이 맞으면 마지막 규칙이 결정합니다.
context와 ignore 규칙
build context는 빌더가 접근할 수 있는 입력 집합이다
docker build .의 .은 build context입니다. 그 안의 파일은 Dockerfile의 COPY와 ADD가 접근할 수 있고, 특히 원격 builder에서는 불필요한 context가 전송량과 노출 범위를 키웁니다. BuildKit이 필요한 파일을 지연 전송할 수 있어도 context를 넓게 잡을 이유는 없습니다.
# 빌드 컨텍스트 크기 확인
docker build --no-cache --progress=plain . 2>&1 | grep "transferring context"
# 원격 데몬을 쓴다면 네트워크 대역폭도 소모됨
DOCKER_HOST=tcp://remote:2376 docker build ..dockerignore 문법 — .gitignore와 비슷하지만 Docker build 입력을 줄이는 목적이다
.dockerignore 파일은 빌드 컨텍스트에서 제외할 경로 패턴을 지정합니다. 와일드카드(*, **)와 부정 패턴(!)을 지원합니다. .gitignore와 문법이 비슷해 보이지만 별개의 파일이며, .gitignore에 적어도 Docker는 자동으로 제외하지 않습니다. Docker build 성능 최적화의 첫 단계입니다.
# 의존성 (재설치하므로 불필요)
node_modules
vendor
# 버전 관리 메타데이터
.git
.gitignore
# 빌드 산출물
dist
build
.next
# 민감 파일 (절대 이미지에 포함되면 안 됨)
.env
*.pem
*.key
secrets/
# 부정 패턴 — 특정 파일만 포함
!dist/server.jsnode_modules와 .git을 제외해야 하는 이유 — 빌드 시간, 보안, 캐시 효율 모두 영향을 받는다
node_modules를 컨텍스트에 포함하면 수백 MB를 전송하고, Dockerfile에서 RUN npm ci가 어차피 새로 설치하므로 전송한 파일은 쓰이지 않습니다. .git은 커밋 히스토리 전체를 포함하므로 크고, 실수로 이미지에 복사되면 소스 이력이 노출됩니다. .env 파일이 포함되면 환경 변수 값이 이미지 레이어에 남아 보안 위험이 생깁니다.
# .dockerignore 없이 빌드할 때
# Sending build context to Docker daemon 450MB
# .dockerignore 추가 후
# Sending build context to Docker daemon 2.1MBsecret과 Dockerfile별 규칙
.gitignore에 등록해도 Docker build에서는 자동으로 제외되지 않는다. Docker는 .dockerignore만 별도로 읽으므로, .env나 *.pem 같은 민감 파일은 반드시 .dockerignore에도 명시해야 한다. 이미지에 비밀 파일이 한 번 포함되면 레이어로 남아 docker history나 이미지 추출로 복구될 수 있다.
참고 링크
2 sources