[IT-정보] 컴포즈 build 옵션 원리 심화 – 빌드 컨텍스트의 동작 원리 – 이미지 빌드 속도를 높이는 컨텍스트 최적화 비결을 공개해요

💡 알아두기
컴포즈 빌드는 단순히 명령을 내리는 과정이 아니라, 로컬 디렉토리의 상태를 압축하여 도커 엔진으로 전달하는 데이터 전송 과정이 포함되어 있어요.

이 글에서 다루는 핵심 내용

• 빌드 컨텍스트의 정의와 전송 메커니즘
• 도커 엔진과 빌드킷(BuildKit)의 상호작용
• build 옵션 설정값이 반영되는 내부 경로와 과정
• 효율적인 이미지 생성을 위한 최적화 설계 전략

빌드 메커니즘 이해를 위한 사전 지식

본격적으로 내부 동작을 뜯어보기 전에, 우리가 다루는 용어들과 기본 전제 조건들을 명확히 짚고 넘어가야 해요. 컴포즈의 build 옵션은 단순히 Dockerfile의 위치를 지정하는 것을 넘어, 빌드 작업의 ‘영역’을 규정하는 아주 중요한 역할을 수행해요.

가장 먼저 이해해야 할 개념은 빌드 컨텍스트예요. 이는 도커 빌드 명령이 실행될 때 도커 클라이언트가 도커 데몬에게 전달하는 파일들의 집합을 의미해요. 우리가 컴포즈 파일에서 context: .이라고 설정하면, 현재 디렉토리의 모든 파일이 압축되어 데몬으로 전송될 준비를 마쳐요. 이때 의도치 않게 대용량 데이터가 포함되면 빌드 시작 전부터 심각한 병목 현상이 발생해요.

환경 설정 및 선택 기준 비교

빌드 방식을 결정할 때는 프로젝트의 규모와 배포 환경을 반드시 고려해야 해요. 무조건 최신 기술을 쓰는 것보다, 현재 팀의 운영 역량에 맞는 방식을 선택하는 것이 더 중요해요.

비교 항목	기본 빌드 방식	BuildKit 활용 방식
빌드 속도	레이어 순차 처리로 상대적으로 느림	병렬 처리 및 캐싱 최적화로 매우 빠름
컨텍스트 관리	전체 디렉토리를 압축하여 전송	필요한 파일만 효율적으로 추출 가능
캐시 효율성	사소한 변경에도 캐시 깨짐 발생 가능	의존성 기반의 정밀한 캐싱 지원

따라서 중급 이상의 개발자라면 단순한 docker-compose build 명령에 의존하기보다, BuildKit 환경을 기본으로 설정하고 컨텍스트 범위를 최소화하는 설계를 지향해야 해요. 이것이 바로 효율적인 컨테이너 운영의 첫걸음이에요.

컴포즈 빌드 엔진의 내부 동작 프로세스

이제 컴포즈의 build 옵션이 실행될 때, 내부에서 어떤 일련의 과정이 벌어지는지 아주 깊게 들여다볼게요. 이 과정을 이해하면 왜 특정 파일이 빌드 속도를 늦추는지, 왜 캐시가 작동하지 않는지 명확하게 알 수 있어요.

STEP 1. 빌드 컨텍스트의 패키징과 전송

사용자가 docker-compose build를 실행하면, 컴포즈 엔진은 가장 먼저 YAML 파일에 정의된 context 경로를 확인해요. 이 경로는 단순히 Dockerfile이 있는 위치가 아니라, 도커 엔진에게 넘겨줄 모든 소스 코드가 담긴 데이터 저장소의 경계를 의미해요.

컴포즈는 지정된 경로를 기반으로 모든 파일을 찾아 하나의 거대한 tarball(압축 파일)로 만들어요. 이때 .dockerignore 파일에 명시된 항목들은 제외되지만, 만약 이 파일이 없거나 설정이 미흡하다면 node_modules나 로그 파일, 혹은 거대한 데이터셋까지 전부 압축 대상에 포함돼요. 이렇게 만들어진 압축 파일이 네트워크 소켓이나 로컬 유닉스 소켓을 통해 도커 데몬으로 전송되는 과정이 빌드 시작 전의 ‘대기 시간’을 결정하는 핵심 요소예요.

STEP 2. 도커 데몬과 빌드킷(BuildKit)의 협업

데이터 전송이 완료되면, 이제 제어권은 도커 엔진(Daemon)으로 넘어가요. 현대적인 도커 환경에서는 이 단계에서 BuildKit이라는 고성능 빌드 엔진이 투입돼요. 과거의 빌드 방식이 명령어를 한 줄씩 순차적으로 실행하는 방식이었다면, BuildKit은 훨씬 똑똑한 방식으로 동작해요.

BuildKit은 빌드 단계를 하나의 유향 비순환 그래프(DAG, Directed Acyclic Graph)로 변환해요. 즉, 어떤 명령어가 어떤 파일에 의존하고 있는지, 어떤 단계가 동시에 실행될 수 있는지를 계산해요. 예를 들어, 소스 코드를 복사하는 단계와 패키지 매니저를 업데이트하는 단계가 서로 독립적이라면, BuildKit은 이를 병렬로 처리하여 전체 빌드 시간을 단축해요. 또한, 각 단계의 결과물을 세밀하게 캐싱하여 변경되지 않은 부분은 건너뛰는 능력이 탁월해요.

STEP 3. build 옵션 내 설정값의 매핑 과정

컴포즈 파일의 build 섹션에는 다양한 하위 옵션이 존재해요. 이 값들이 어떻게 내부적으로 반영되는지 아는 것이 설계의 핵심이에요.

• context: 위에서 설명한 대로, 엔진이 바라볼 파일 시스템의 뿌리를 지정해요.
• dockerfile: 컨텍스트 내부에서 사용할 설계도 파일의 이름을 지정해요. 기본값은 Dockerfile이지만, 서비스마다 다른 설정(예: dev.Dockerfile)을 사용해야 할 때 유용해요.
• args: 빌드 시점에만 주입되는 변수예요. 이는 컨테이너 실행 시 사용하는 environment와는 완전히 달라요. 빌드 단계에서 특정 라이브러리 버전을 결정하거나, 빌드 전용 API 키를 전달할 때 사용돼요.

STEP 4. 리소스 생성과 레이어 아카이빙

이제 실제 이미지 레이어가 만들어지는 단계예요. Dockerfile의 각 명령(RUN, COPY, ADD 등)은 독립적인 레이어를 생성해요. 여기서 중요한 점은 레이어의 영속성이에요. 한번 생성된 레이어는 해시(Hash) 값으로 식별되며, 동일한 명령과 동일한 파일 내용이 입력되면 기존 레이어를 그대로 재사용해요.

하지만 COPY . .과 같이 컨텍스트 전체를 복사하는 명령을 사용하면 문제가 발생해요. 소스 코드 중 아주 작은 파일 하나만 바뀌어도 전체 파일의 해시 값이 변하기 때문에, 그 이후의 모든 레이어 캐시가 무효화(Invalidation)되어 버려요. 결국 모든 명령어를 처음부터 다시 실행해야 하는 비효율이 발생하는 것이죠.

STEP 5. 실무 최적화 시나리오: 멀티 스테이지 빌드

전문적인 개발자들은 위에서 언급한 문제를 해결하기 위해 멀티 스테이지 빌드(Multi-stage Build)를 적극 활용해요. 이는 하나의 Dockerfile 안에 여러 개의 FROM 절을 사용하여, 빌드에 필요한 도구와 실제 실행에 필요한 결과물을 분리하는 기법이에요.

예를 들어, Java 애플리케이션을 빌드할 때 첫 번째 스테이지에서는 Maven이나 Gradle을 사용하여 수백 MB의 의존성 라이브러리와 빌드 도구를 사용해요. 하지만 최종 이미지를 만드는 두 번째 스테이지에서는 빌드가 완료된 가벼운 .jar 파일만 가져와서 아주 작은 JRE 환경 위에서 실행해요. 이렇게 하면 최종 이미지 크기가 획기적으로 줄어들 뿐만 아니라, 빌드 과정에서 생성된 불필요한 캐시와 소스 코드가 최종 이미지에 포함되지 않아 보안성도 높아져요.

자주 하는 실수와 해결법

현장에서 개발자들이 가장 흔하게 저지르는 실수들을 정리했어요. 이 패턴만 피해도 빌드 효율이 비약적으로 상승할 거예요.

• ❌ 컨텍스트에 대용량 파일을 포함시키는 실수
  왜 발생하는가: context: .으로 설정하고 .dockerignore를 작성하지 않아서 발생해요.
  ✅ 해결법: 데이터셋, 로그 파일, 로컬 가상환경 폴더(venv, node_modules)를 반드시 .dockerignore에 등록하세요.
• ❌ 레이어 캐시 순서를 무시하는 실수
  왜 발생하는가: 소스 코드를 먼저 복사한 뒤 의존성을 설치하면, 코드 한 줄 바뀔 때마다 매번 패키지를 다시 다운로드하게 돼요.
  ✅ 해결법: 의존성 정의 파일(package.json, requirements.txt 등)을 먼저 복사하고 설치 명령을 실행한 뒤, 마지막에 소스 코드를 복사하세요.
• ❌ build 옵션의 args와 env를 혼동하는 실수
  왜 발생하는가: 빌드 시 필요한 설정과 실행 시 필요한 설정을 구분하지 못해서 발생해요.
  ✅ 해결법: 빌드 중에만 필요한 값은 build > args에, 컨테이너 운영 중에 필요한 값은 environment에 정의하세요.
• ❌ 상대 경로 설정 오류
  왜 발생하는가: 컨텍스트 경로를 잘못 지정하여 Dockerfile 내부의 COPY 명령이 파일을 찾지 못해요.
  ✅ 해결법: context가 가리키는 디렉토리를 기준으로 모든 상대 경로가 계산된다는 점을 명심하세요.
• ❌ BuildKit 비활성화 상태로 작업
  왜 발생하는가: 구형 도커 엔진을 사용하거나 설정을 누락하여 병렬 빌드 혜택을 못 받아요.
  ✅ 해결법: 환경 변수 DOCKER_BUILDKIT=1을 설정하거나 최신 버전의 Docker Desktop을 사용하세요.

자주 묻는 질문

Q. docker-compose build와 docker-compose up의 차이는 무엇인가요?

build는 오직 이미지를 만드는 과정에 집중해요. 반면 up은 이미지가 없을 경우 build를 먼저 수행한 뒤, 생성된 이미지를 기반으로 컨테이너를 실행하는 전체 프로세스를 담당해요.

Q. 빌드 속도를 높이는 가장 확실한 방법은 무엇인가요?

가장 먼저 .dockerignore를 사용하여 컨텍스트 크기를 줄이세요. 그다음으로 레이어 캐시가 깨지지 않도록 Dockerfile의 명령 순서를 최적화하는 것이 정석이에요.

Q. .dockerignore 파일은 어디에 두어야 하나요?
Q. 빌드 중에 환경 변수를 넣으려면 어떻게 해요?

모든 무시 규칙은 빌드 컨텍스트의 루트 디렉토리에 위치해야 해요. 빌드 시 변수를 주입하려면 Dockerfile에서 ARG 명령어를 선언하고, 컴포즈 파일의 build 섹션에서 args를 통해 값을 넘겨주면 돼요.

효율적인 빌드 설계를 위한 마무리

지금까지 컴포즈의 build 옵션이 단순한 명령어를 넘어, 어떻게 방대한 데이터를 처리하고 최적화된 이미지를 만들어내는지 그 내부 메커니즘을 살펴봤어요. 빌드 과정의 병목은 대부분 우리가 무심코 지나친 컨텍스트 설정과 레이어 설계에서 비롯된다는 점을 꼭 기억해 주세요.

오늘 배운 내용을 바탕으로 지금 바로 여러분의 프로젝트를 점검해 보세요. 프로젝트 루트에 .dockerignore가 있는지, 그리고 Dockerfile의 명령 순서가 효율적인지 확인하는 것만으로도 큰 변화를 경험할 수 있어요.

직접 명령어로 리소스를 조회하며 글의 설명을 확인해 보세요. 예를 들어 docker system df 명령어를 통해 현재 이미지와 빌드 캐시가 차지하는 용량을 확인해 보는 것도 좋은 시작이에요.

관련하여 더 깊은 기초가 필요하다면 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드 글을 참고해 보세요.