[IT-정보] 컴포즈 build 옵션 오류 해결 완벽 가이드 – 원인별 진단 순서와 실무 해결 방법 정리

왜 빌드 옵션 오류가 운영의 발목을 잡을까요

새로운 마이크로서비스를 배포하려고 docker-compose up --build 명령어를 입력했는데, 갑자기 빨간색 오류 메시지가 화면을 가득 채우는 상황을 경험해 보셨나요? 분명 개발 환경에서는 잘 돌아가던 설정이 운영 서버나 스테이징 환경으로 넘어오기만 하면 빌드 컨텍스트(build context)를 찾을 수 없다거나, 파일을 찾을 수 없다는 식의 메시지를 뱉어내곤 해요. 이런 오류는 단순히 명령어 하나를 잘못 입력해서 생기는 경우보다, 설정 파일 내부의 경로 구조나 빌드 옵션 간의 유기적인 관계를 놓쳤을 때 발생하는 경우가 훨씬 많아요.

서버 운영 담당자에게 이런 빌드 오류는 단순한 불편함을 넘어 배포 파이프라인을 중단시키는 심각한 장애로 이어지기도 해요. 특히 컨테이너 운영 규모가 커질수록 각 서비스의 docker-compose.yml 파일은 복잡해지고, 빌드 옵션 하나가 꼬이면 전체 시스템의 업데이트가 지연되는 상황이 벌어져요. 원인을 알 수 없는 빌드 실패는 운영자의 피로도를 높이고, 장애 대응 시간을 불필요하게 늘리는 주범이 되기도 하죠.

이 글에서는 단순히 오류 메시지를 읽어주는 것에 그치지 않고, 컴포즈 build 옵션 오류 해결을 위한 체계적인 접근법을 제안하려고 해요. 어떤 순서로 로그를 분석해야 하는지, 경로 설정에서 흔히 범하는 실수는 무엇인지, 그리고 어떻게 하면 이런 오류가 재발하지 않도록 설정을 최적화할 수 있는지 실무적인 관점에서 하나씩 짚어드릴게요.

이 글을 다 읽고 나면 여러분은 다음과 같은 능력을 갖추게 될 거예요.

• 복잡한 빌드 오류 메시지 속에서 핵심 원인을 빠르게 추출하는 법
• 빌드 컨텍스트와 Dockerfile 경로 사이의 논리적 관계 이해
• 효율적인 컨테이너 빌드를 위한 옵션 최적화 능력
• 재발 방지를 위한 .dockerignore 및 설정 관리 전략

오류를 마주하기 전 갖춰야 할 기본 지식

문제를 해결하기 위해서는 먼저 우리가 조작하고 있는 도구의 동작 원리를 명확히 이해해야 해요. 도커 컴포즈에서 build 옵션은 단순히 이미지를 만드는 명령을 넘어, 어떤 파일들을 도커 엔진으로 보낼지 결정하는 매우 중요한 설정이에요. 이 과정에서 가장 혼동하기 쉬운 개념이 바로 빌드 컨텍스트와 Dockerfile의 위치예요.

빌드 컨텍스트란 도커 클라이언트가 빌드 프로세스를 시작할 때 도커 데몬(Docker Daemon)으로 전송하는 파일들의 집합을 의미해요. docker-compose.yml의 context 항목에 지정된 경로가 바로 그 기준점이 되는 거죠. 만약 컨텍스트를 프로젝트 루트로 설정했는데 불필요한 대용량 데이터나 로그 파일이 포함되어 있다면, 빌드 속도가 현저히 느려지거나 네트워크 부하로 인해 빌드가 실패할 수도 있어요.

또한, dockerfile 옵션은 빌드 컨텍스트 내부에서 Dockerfile이 어디에 있는지를 가리켜요. 여기서 많은 운영자가 실수하는 부분이, Dockerfile의 경로를 프로젝트 전체 루트 기준으로 작성해야 한다고 오해하는 것이에요. 하지만 Dockerfile 경로는 반드시 설정된 빌드 컨텍스트를 기준으로 한 상대 경로여야 한다는 점을 꼭 기억해야 해요.

문제를 진단하기 전에 아래 표를 통해 현재 여러분이 사용 중인 설정 방식이 어떤 특징을 갖는지 비교해 보세요.

진단을 시작하기 전에 현재 환경의 도커 버전과 컴포즈 버전을 확인하는 것도 잊지 마세요. 버전 간의 옵션 차이로 인해 특정 문법이 동작하지 않는 경우도 생각보다 자주 발생하거든요. 준비가 되었다면, 이제 본격적으로 오류의 유형을 파헤쳐 보아요.

컴포즈 build 옵션 오류의 핵심 원인과 진단 절차

빌드 오류를 해결하는 과정은 마치 범인을 찾는 수사 과정과 같아요. 증거(로그)를 수집하고, 용의자(설정값)를 좁혀나가며, 마지막으로 결정적인 단서(명령어)를 통해 문제를 해결해야 하죠. 무턱대고 파일을 수정하기보다는 아래의 단계별 가이드를 따라 체계적으로 접근해 보세요.

STEP 1. 빌드 컨텍스트 경로 설정 오류 확인하기

가장 흔하게 발생하는 문제는 context 경로가 실제 파일 시스템 구조와 일치하지 않을 때 발생해요. 컴포즈 파일에서 지정한 경로가 현재 명령어를 실행하는 위치를 기준으로 올바른지를 먼저 확인해야 해요. 만약 `context: ./services/api`라고 적었다면, 실제로 프로젝트 루트 아래에 `services` 폴더가 있고 그 안에 `api` 폴더가 있는지 확인해야 하죠.

특히 상대 경로의 기준점을 혼동하는 경우가 많아요. 컴포즈 파일이 위치한 디렉토리가 기준이 아니라, docker-compose up 명령어를 입력하는 터미널의 현재 작업 디렉토리(PWD)가 기준이 되는 경우가 있으니 주의가 필요해요. 만약 경로가 잘못되었다면 `ls -R` 명령어를 통해 현재 디렉토리 구조를 시각적으로 확인하며 경로를 재검증해 보세요.

STEP 2. Dockerfile 경로와 파일명 매칭 검사

컨텍스트를 잘 설정했더라도, 그 안에서 사용할 Dockerfile을 찾지 못하면 빌드는 중단돼요. dockerfile: Dockerfile.prod와 같이 이름을 변경했다면, 컴포즈 파일에도 해당 이름이 정확히 명시되어 있어야 해요. 대소문자 구분 하나만 틀려도 리눅스 환경의 컨테이너 빌드에서는 치명적인 오류를 일으킨다는 사실을 명심하세요.

또한, Dockerfile 내의 COPY/ADD 명령어가 참조하는 경로도 반드시 확인해야 해요. Dockerfile 내부에서 사용하는 경로는 ‘빌드 컨텍스트의 루트’를 기준으로 해요. 예를 들어 컨텍스트가 `./app`이고, 그 안에 `src` 폴더가 있다면, Dockerfile에서는 `COPY ./src /app/src`라고 써야 하는 것이지, 프로젝트 전체 루트를 기준으로 `COPY ./app/src /app/src`라고 쓰면 오류가 발생해요. 이 부분은 실무에서 정말 많은 개발자와 운영자를 괴롭히는 지점이에요.

STEP 3. .dockerignore 파일의 영향력 파악

빌드는 성공하는데 정작 컨테이너 내부를 확인해보니 필요한 파일이 하나도 없다면, 범인은 .dockerignore 파일일 확률이 높아요. 이 파일은 빌드 컨텍스트에 포함되지 말아야 할 파일(예: .git, node_modules, 로그 파일 등)을 정의하는 역할을 해요. 하지만 실수로 프로젝트의 핵심 소스 코드 폴더를 여기에 포함해 버린다면, 도커 엔진은 해당 파일을 무시하게 되고 빌드 과정에서 ‘파일을 찾을 수 없음’ 오류를 발생시켜요.

실제로 많은 팀에서 보안을 위해 `.env` 파일을 제외하도록 설정했다가, 빌드 타임에 환경 변수 파일이 필요해지면서 빌드가 깨지는 상황을 겪곤 해요. 이럴 때는 `.dockerignore`를 일시적으로 비우고 빌드를 시도하여 원인이 이 파일에 있는지 확인하는 것이 좋은 전략이에요.

STEP 4. 빌드 캐시 오염 및 버전 불일치 문제

설정이 완벽한데도 불구하고 어제는 됐던 빌드가 오늘은 안 된다면, 빌드 캐시(Build Cache)를 의심해야 해요. 도커는 빌드 속도를 높이기 위해 이전 빌드에서 사용했던 레이어를 저장해 두는데, 이 캐시가 꼬이거나 이전 버전의 라이브러리 정보가 남아 있으면 논리적으로 맞지 않는 이미지가 생성될 수 있어요.

이럴 때는 캐시를 완전히 무시하고 처음부터 다시 빌드하는 명령어를 사용해야 해요.
docker-compose build --no-cache
이 명령어를 사용하면 도커는 기존의 캐시를 전혀 사용하지 않고 모든 단계를 새로 수행해요. 시간이 조금 더 걸리더라도, 원인을 알 수 없는 설정 오류를 해결하는 데 가장 강력한 처방전이 될 수 있어요.

STEP 5. 권한 및 파일 시스템 이슈 진단

마지막으로 살펴볼 부분은 운영 환경의 특수성이에요. 서버 운영 환경에서는 docker 명령어를 실행하는 사용자의 권한 문제나, 파일 시스템의 읽기 전용(Read-only) 설정 때문에 빌드가 실패할 수 있어요. 특히 CI/CD 파이프라인(Jenkins, GitHub Actions 등)을 통해 빌드를 수행할 때는, 해당 에이전트가 프로젝트 디렉토리에 접근할 수 있는 권한이 있는지 반드시 체크해야 해요.

또한, 디스크 공간이 부족한 경우에도 빌드 프로세스가 중간에 중단되며 알 수 없는 오류 메시지를 남기기도 하죠. df -h 명령어로 디스크 용량을 확인하고, docker system prune 명령어를 통해 사용하지 않는 오래된 이미지와 컨테이너를 정리하여 공간을 확보하는 작업이 필요할 수 있어요.

실무 적용 시나리오: 마이크로서비스 빌드 실패 사례

한 예시를 들어볼게요. 운영 팀의 A 담당자는 `order-service`라는 마이크로서비스를 배포하려고 했어요. 그런데 다음과 같은 상황이 발생했죠.

• 상황: docker-compose build 실행 시 'COPY failed: stat /app/config/db.yaml: no such file or directory' 오류 발생.
• 분석: 1) `order-service/docker-compose.yml`의 `context`가 `./`로 되어 있음. 2) `Dockerfile`에서 `COPY config/db.yaml`을 시도함. 3) 하지만 실제 `config` 폴더는 `order-service/config`가 아니라 프로젝트 전체 루트의 `configs/`에 위치함.
• 해결: `context`를 프로젝트 루트로 넓히거나, 혹은 `config` 폴더를 `order-service` 내부로 이동시킨 후 빌드를 다시 수행함.

이처럼 오류는 항상 설정 간의 ‘불일치’에서 시작된다는 점을 잊지 마세요.

자주 하는 실수와 해결법 및 FAQ

자주 하는 실수와 해결법

현장에서 운영자들이 가장 빈번하게 겪는 실수들을 정리했어요. 비슷한 상황을 겪고 있다면 이 리스트를 먼저 확인해 보세요.

• ❌ 실수: context 경로를 프로젝트 루트 기준으로 작성함
  ✅ 해결법: 컴포즈 파일 위치를 기준으로 한 상대 경로인지, 혹은 명령어를 실행하는 위치가 어디인지 재확인하세요.
• ❌ 실수: .dockerignore에 필요한 설정 파일이 포함됨
  ✅ 해결법: 빌드 중 누락되는 파일이 있다면 `.dockerignore` 내용을 하나씩 주석 처리하며 범인을 찾으세요.
• ❌ 실수: Dockerfile 내의 경로를 컨텍스트 외부로 지정함
  ✅ 해결법: Dockerfile은 오직 지정된 컨텍스트 폴더 안의 파일만 참조할 수 있다는 원칙을 지키세요.
• ❌ 실수: 이전 빌드 결과물이 남아 있어 설정 변경이 반영 안 됨
  ✅ 해결법: --no-cache 옵션을 사용하여 깨끗한 상태에서 다시 빌드하세요.
• ❌ 실수: 파일 권한 문제로 빌드 중 파일 읽기 실패
  ✅ 해결법: 빌드 실행 계정이 해당 디렉토리에 대해 읽기 권한을 가지고 있는지 ls -l로 확인하세요.

자주 묻는 질문

Q. 빌드 컨텍스트가 너무 커서 빌드 속도가 너무 느려요. 어떻게 하나요?

가장 먼저 `.dockerignore` 파일을 점검해야 해요. `node_modules`, `.git`, 대용량 로그 파일, 로컬 데이터베이스 파일 등이 컨텍스트에 포함되어 있다면 빌드 전 모든 파일을 도커 엔진으로 전송하는 데 엄청난 시간이 소요돼요. 불필요한 파일들을 철저히 제외하도록 설정하세요.

Q. 특정 환경에서만 build 옵션 오류가 발생하는데 원인이 뭘까요?
개발 PC와 운영 서버의 OS 환경 차이를 의심해 봐야 해요. 예를 들어, 파일 시스템의 대소문자 구분 여부(Case-sensitivity)가 다르거나, 운영 서버의 디스크 용량이 부족한 경우, 혹은 도커 버전이 낮아 특정 옵션을 지원하지 않는 경우일 수 있어요.

Q. Dockerfile을 여러 개 사용할 때 컴포즈에서 어떻게 지정하나요?
docker-compose.yml의 `build` 섹션 아래에 `dockerfile: path/to/Dockerfile.name` 형식을 사용하여 명시적으로 지정해 주면 돼요. 이때 `context`와 `dockerfile` 사이의 경로 관계를 반드시 체크해야 해요.

Q. 빌드 중에 환경 변수를 전달하고 싶은데 어떻게 하나요?
`args` 옵션을 사용해야 해요. `docker-compose.yml`의 `build` 섹션에 `args`를 정의하고, `Dockerfile` 내부에서 `ARG` 명령어로 해당 변수를 선언하여 사용하면 빌드 타임에 값을 주입할 수 있어요.

Q. 캐시를 지우지 않고 특정 단계만 다시 빌드할 수 있나요?
아쉽게도 도커는 특정 레이어만 골라서 캐시를 무효화하는 기능은 제공하지 않아요. 다만, `Dockerfile` 내의 `COPY` 명령 바로 위에 `RUN touch /tmp/force-rebuild`와 같이 파일의 변경을 유도하는 명령을 넣어 해당 지점부터 캐시를 깨뜨리는 트릭을 사용할 수는 있어요.

안정적인 컨테이너 운영을 위한 마무리

컴포즈 빌드 오류는 한 번 겪으면 매우 당혹스럽지만, 원리만 이해하면 의외로 명확한 답이 나오는 영역이에요. 결국 핵심은 ‘경로의 일관성’과 ‘컨텍스트의 최적화’로 귀결돼요. 오늘 배운 내용을 바탕으로 운영 환경의 빌드 프로세스를 점검해 보시길 바라요.

장애가 발생했을 때 당황하지 않고 진단 순서를 따라가는 것이 가장 중요해요. 오늘부터는 오류가 발생하면 바로 수정하기보다, 로그를 먼저 분석하고 위에서 언급한 5단계 진단 절차를 체크리스트로 활용해 보세요. 문제를 해결하는 속도가 훨씬 빨라질 거예요.

지금 바로 실행해 보세요:

• 오늘 운영 중인 서비스의 docker-compose.yml 파일에서 context와 dockerfile 경로가 최신 구조와 맞는지 확인해 보세요.
• 불필요하게 큰 용량의 파일이 빌드 컨텍스트에 포함되어 있지는 않은지 `.dockerignore`를 점검해 보세요.

같은 오류가 반복된다면 오늘 정리한 진단 순서를 자신만의 체크리스트로 만들어 두는 것을 추천해요. 반복되는 장애를 막는 가장 확실한 방법은 기록과 반복된 검증이니까요.

도커 컴포즈의 기본 개념을 더 깊이 있게 이해하고 싶다면, 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드 글을 함께 읽어보시면 큰 도움이 될 거예요.