[IT-방법] 컴포즈 build 옵션 자동화 기술 – CI/CD 연동으로 반복되는 배포 업무를 줄여요

매번 명령어를 입력하는 배포 과정의 피로감

퇴근을 코앞에 둔 금요일 저녁, 갑자기 발견된 버그를 수정하고 배포를 시도한다고 상상해 보세요. 터미널을 열고 익숙하게 docker-compose build 명령어를 입력하지만, 이번에는 특정 버전을 지정하기 위해 복잡한 build 옵션을 길게 나열해야 해요. 명령어를 한 줄이라도 잘못 타이핑하면 빌드는 실패하고, 어디서부터 잘못되었는지 확인하느라 귀중한 시간만 흘러가게 돼요.

이런 상황은 단순히 귀찮은 문제를 넘어 서비스의 안정성을 해칠 수 있는 위험 요소예요. 수동으로 명령어를 입력하는 과정에서 발생하는 작은 실수가 운영 서버의 설정 오류로 이어지고, 결국 서비스 장애라는 결과로 나타날 수 있기 때문이에요. 반복되는 배포 작업은 개발자의 집중력을 흐트러뜨리고, 더 가치 있는 코드 작성 시간을 빼앗아 가요.

이제는 사람이 직접 명령어를 치는 시대에서 벗어나야 해요. 컴포즈 build 옵션 자동화는 단순히 편의를 위한 기능이 아니라, 지속 가능한 운영 환경을 만들기 위한 필수적인 전략이에요. 빌드 컨텍스트를 정교하게 제어하고, CI/CD 파이프라인과 연동하여 사람의 개입을 최소화하는 것이 핵심이에요.

이 글을 끝까지 읽고 나면 다음과 같은 능력을 갖추게 될 거예요.

• 컴포즈 build 옵션의 핵심 메커니즘 이해
• 빌드 컨텍스트 최적화를 통한 빌드 속도 개선
• CI/CD 파이프라인에 빌드 프로세스 통합하기
• 배포 실패 시 안전하게 되돌리는 롤백 전략 수립

자동화를 시작하기 전 꼭 챙겨야 할 기초 지식

본격적으로 자동화 스크립트를 짜기 전에, 우리가 무엇을 자동화하려 하는지 정확히 파악해야 해요. 도커 컴포즈의 build 섹션은 단순히 이미지를 만드는 것을 넘어, 빌드 시점에 필요한 환경 정보를 주입하는 복잡한 통로 역할을 해요. 이를 제대로 이해하지 못한 채 자동화만 시도하면, 오히려 디버깅하기 더 어려운 시스템을 만들게 될 수도 있어요.

빌드 컨텍스트와 도커파일의 관계

가장 먼저 이해해야 할 개념은 빌드 컨텍스트(Build Context)예요. 빌드 컨텍스트는 도커 데몬이 이미지를 빌드할 때 사용할 수 있는 파일들의 범위예요. 만약 컨텍스트를 프로젝트 루트로 너무 넓게 잡으면, 불필요한 파일까지 도커 데몬으로 전송되어 빌드 속도가 급격히 느려져요. 반대로 너무 좁게 잡으면 빌드에 필요한 설정 파일을 찾지 못해 오류가 발생하죠.

또한, build-arg와 환경 변수의 차이점도 명확히 구분해야 해요. build-arg는 이미지를 만드는 과정에서만 사용되는 값이고, 환경 변수(environment)는 이미지가 만들어진 후 컨테이너가 실행될 때 사용되는 값이에요. 이 둘을 혼동해서 자동화 로직을 짜면, 런타임에 필요한 설정값이 이미지에 포함되지 않아 서비스가 구동되지 않는 상황을 맞이하게 돼요.

자동화 방식 선택 기준 비교

어떤 수준까지 자동화할지는 현재 팀의 상황과 인프라 규모에 따라 달라져요. 아래 표를 통해 본인에게 맞는 단계를 선택해 보세요.

처음부터 너무 거창한 시스템을 구축하려 하지 마세요. 우선은 가장 자주 반복하는 명령어 하나를 스크립트로 만드는 것부터 시작하는 것이 가장 효율적이에요.

단계별 컴포즈 build 옵션 자동화 실행 가이드

이제 이론을 넘어 실제 실무에서 어떻게 컴포즈 build 옵션을 자동화하고 파이프라인을 설계하는지 단계별로 살펴볼게요. 이 과정은 단순히 명령어를 모으는 것이 아니라, 빌드의 일관성을 유지하고 배포의 안정성을 확보하는 과정이에요.

STEP 1. 빌드 컨텍스트와 경로 최적화하기

자동화의 첫걸음은 docker-compose.yml 파일 내의 build 설정을 정교하게 다듬는 거예요. 많은 개발자가 실수하는 부분 중 하나가 모든 파일을 빌드 컨텍스트에 포함시키는 것이에요. 자동화 스크립트를 작성하기 전에, 먼저 각 서비스가 어떤 파일에 의존하는지 명확히 정의해야 해요.

예를 들어, 특정 서비스의 도커파일이 프로젝트 루트가 아닌 sub-directory에 있다면, context 경로를 정확히 지정해 주어야 해요. 이렇게 하면 도커 데몬이 필요한 파일만 읽어 들여 빌드 효율이 극대화돼요. 자동화 스크립트에서는 이 경로를 환경 변수로 관리하여, 개발 환경과 운영 환경의 폴더 구조가 다르더라도 유연하게 대응할 수 있도록 설계해야 해요.

STEP 2. 동적 build-arg를 활용한 환경 변수 주입

서비스의 버전 번호나 환경 설정(staging, production)을 빌드 시점에 결정해야 할 때가 있어요. 이때 build-arg를 자동화하는 것이 매우 중요해요. 수동으로 빌드할 때는 명령어를 길게 입력해야 하지만, 자동화 환경에서는 이 값들을 외부 소스에서 가져와 동적으로 주입할 수 있어요.

자동화 스크립트에서는 다음과 같은 논리 구조를 가집니다. 먼저 현재 Git의 커밋 해시나 태그 정보를 가져온 뒤, 이를 컴포즈 명령어의 인자로 전달하는 방식이에요. 이렇게 하면 생성된 이미지에 어떤 코드가 포함되어 있는지 명확하게 추적할 수 있어요.

STEP 3. 쉘 스크립트를 이용한 명령어 체계화

CI/CD 도구를 도입하기 전 단계로, 모든 빌드 명령어를 하나의 실행 가능한 파일로 만드는 과정이 필요해요. 단순히 docker-compose build를 적어두는 것에 그치지 말고, 예외 처리가 포함된 로직을 구현해야 해요.

예를 들어, 빌드 전 기존의 미사용 컨테이너를 정리하는 docker system prune 과정을 포함하거나, 빌드 실패 시 에러 메시지를 로그 파일로 저장하는 기능을 넣을 수 있어요. 이렇게 작성된 스크립트는 개발자 개개인의 환경이 아닌, 표준화된 배포 환경을 제공하는 역할을 수행하게 돼요.

STEP 4. CI/CD 파이프라인 통합하기

이제 작성한 스크립트나 명령어를 GitHub Actions와 같은 도구에 이식할 차례예요. CI/CD 파이프라인은 사람이 개입하지 않아도 코드가 머지(merge)되는 순간 빌드부터 배포까지 일사천리로 진행하게 만들어요.

파이프라인 설계 시 주의할 점은 빌드 캐시(Build Cache)를 어떻게 관리할 것인가 하는 문제예요. 매번 처음부터 빌드하면 시간이 너무 오래 걸리므로, CI 서버의 캐시 기능을 활용하여 변경되지 않은 레이어는 재사용하도록 설정해야 해요. 또한, 빌드가 완료된 이미지는 Docker Registry에 자동으로 푸시(push)되도록 하여, 운영 서버에서는 이미지 이름과 태그만 지정해 pull 할 수 있는 구조를 만들어야 해요.

STEP 5. 배포 후 자동 검증 단계 구성

빌드가 성공했다고 해서 배포가 성공한 것은 아니에요. 자동화된 파이프라인의 마지막 단계는 반드시 검증(Verification) 단계여야 해요. 컨테이너가 실행된 후, 애플리케이션이 정상적으로 응답하는지 확인하는 ‘헬스 체크(Health Check)’를 자동화하세요.

예를 들어, 특정 엔드포인트에 HTTP 요청을 보내서 200 OK 응답이 오는지 확인하는 스크립트를 파이프라인 끝에 배치하는 것이에요. 만약 검증 단계에서 실패한다면, 시스템은 즉시 경고를 보내고 다음 단계인 롤백(Rollback) 프로세스를 트리거해야 해요. 이 과정까지 자동화되어야 비로소 ‘배포를 손에서 놓는’ 진정한 자동화가 완성되었다고 할 수 있어요.

자주 하는 실수와 해결법

자동화 시스템을 구축하다 보면 예상치 못한 변수들 때문에 빌드가 멈추거나 엉뚱한 결과가 나올 때가 많아요. 실무에서 가장 빈번하게 발생하는 문제들을 정리해 보았으니, 비슷한 상황을 겪고 있다면 확인해 보세요.

• ❌ 실수: 빌드 컨텍스트를 프로젝트 루트로 설정하여 빌드 속도가 매우 느려짐
  왜 발생하는가: 모든 파일을 전송하려다 보니 불필요한 로그, 임시 파일, 라이브러리까지 포함되기 때문이에요.
  ✅ 해결법: .dockerignore 파일을 생성하여 필요한 파일만 빌드 대상에 포함하세요.
• ❌ 실수: build-arg로 비밀번호를 전달하여 보안 사고 발생
  왜 발생하는가: build-arg는 이미지 레이어 정보에 평문으로 남기 때문이에요.
  ✅ 해결법: 보안이 필요한 정보는 컨테이너 실행 시점에 environment 옵션이나 Docker Secrets를 사용하세요.
• ❌ 실수: 로컬 환경과 CI 환경의 경로 차이로 인한 빌드 실패
  왜 발생하는가: 상대 경로를 하드코딩하여 환경이 바뀌면 파일을 찾지 못하기 때문이에요.
  ✅ 해결법: 경로 설정을 환경 변수로 관리하고, 스크립트 내에서 현재 작업 디렉토리를 동적으로 파악하세요.
• ❌ 실수: 캐시 문제로 인해 수정된 코드가 반영되지 않음
  왜 발생하는가: 이전 빌드의 레이어가 남아 있어 새로운 변경 사항을 무시하기 때문이에요.
  ✅ 해결법: 중요한 변경 시에는 --no-cache 옵션을 사용하거나, 캐시 키를 관리하는 전략을 세우세요.
• ❌ 실수: 배포 후 서비스가 구동되지 않는데 성공으로 표시됨
  왜 발생하는가: 컨테이너 실행 명령 자체는 성공했지만, 애플리케이션 내부 오류로 실제 서비스는 죽어있기 때문이에요.
  ✅ 해결법: 파이프라인 마지막 단계에 반드시 HTTP 상태 코드를 확인하는 검증 스크립트를 추가하세요.

자주 묻는 질문

Q. 컴포즈 build 옵션 자동화를 하면 배포 속도가 빨라지나요?

단순히 빌드 자체의 시간이 줄어드는 것은 아니지만, 명령어를 입력하고 확인하는 과정에서의 휴먼 에러와 대기 시간을 획기적으로 줄여주기 때문에 전체적인 배포 사이클(Cycle Time)은 훨씬 빨라져요.

Q. CI/CD 도구 없이 쉘 스크립트만으로도 충분할까요?

네, 충분해요. 처음부터 복잡한 도구를 도입하기보다는, 자주 쓰는 명령어를 쉘 스크립트로 묶어서 관리하는 것만으로도 업무 효율이 비약적으로 상승하는 것을 경험하실 수 있어요.

Q. 빌드 시 사용하는 build-arg는 이미지 용량에 영향을 주나요?
직접적인 용량 증가보다는, 인자값에 따라 레이어가 갈라지면서 캐시 효율성에 영향을 줄 수 있어요. 레이어 전략을 잘 짜는 것이 중요해요.

Q. 롤백은 어떻게 자동화하는 것이 가장 좋은가요?

가장 권장하는 방법은 이전 단계에서 성공했던 이미지 태그를 기억해 두었다가, 검증 실패 시 해당 태그로 다시 docker-compose up을 실행하는 스크립트를 구성하는 것이에요.

더 나은 자동화를 위한 다음 여정

지금까지 컴포즈 build 옵션 자동화를 통해 반복적인 업무를 줄이고 배포의 안정성을 높이는 방법을 자세히 살펴보았어요. 자동화는 한 번에 완성되는 것이 아니라, 시스템을 운영하며 끊임없이 다듬어가는 과정이에요.

이제 여러분이 해야 할 일은 명확해요. 오늘 당장 터미널에서 가장 자주 입력하는 명령어 하나를 찾아보세요. 그리고 그것을 아주 간단한 .sh 파일로 만드는 것부터 시작해 보세요. 그 작은 시작이 여러분의 퇴근 시간을 앞당겨줄 거예요.

다음 단계로 나아가고 싶다면, 구축한 자동화 스크립트를 GitHub Actions의 워크플로우 파일로 옮겨보는 연습을 추천해요. 인프라를 코드로 관리하는 IaC(Infrastructure as Code) 개념까지 익히게 된다면, 여러분은 단순한 개발자를 넘어 진정한 데브옵스 역량을 갖춘 엔지니어로 성장하게 될 거예요.

가장 자주 반복하는 명령 하나부터 스크립트로 옮겨 보세요. 작은 자동화가 모여 거대한 안정성을 만듭니다.

도커 컴포즈의 더 깊은 활용법이 궁금하다면, 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드를 함께 읽어보시는 것을 추천해요.