[IT-방법] 컴포즈 build 옵션 자동화와 CI/CD 연동 – 반복되는 배포 작업에서 해방되는 법

반복되는 빌드 명령어, 언제까지 직접 치고 계실 건가요?

퇴근 직전, 마지막 배포를 위해 터미널을 켭니다. 평소처럼 docker-compose build 명령어를 입력하지만, 갑자기 오류가 발생해요. 확인해 보니 빌드 인자(build-arg) 하나를 빼먹었네요. 다시 명령어를 입력하고 10분 동안 빌드가 끝나기를 기다립니다. 이 과정을 매일, 혹은 매주 반복하고 있다면 지금 바로 변화가 필요한 시점이에요.

수동 배포는 단순히 귀찮은 문제가 아니에요. 사람이 하는 일에는 반드시 실수가 따르기 마련이고, 그 실수는 곧 서비스 장애로 이어지기도 하죠. 특히 빌드 컨텍스트(Build Context) 설정을 잘못하여 불필요한 파일까지 빌드 서버로 전송하면, 빌드 시간만 늘어나는 게 아니라 네트워크 비용과 스토리지 낭비까지 초래해요. 효율적인 개발 환경을 만드는 것은 단순히 편해지기 위함이 아니라, 서비스의 안정성을 확보하는 핵심적인 과정이에요.

이 글을 읽고 나면 여러분은 더 이상 복잡한 명령어를 외우거나 실수할까 봐 불안해하지 않아도 돼요. 컴포즈의 빌드 옵션을 어떻게 최적화하는지, 그리고 이를 어떻게 자동화 파이프라인에 태울 수 있는지 실무적인 관점에서 정리해 드릴게요.

자동화의 시작, 빌드 옵션과 컨텍스트 제대로 이해하기

무작정 스크립트를 짜기 전에, 우리가 무엇을 자동화하려 하는지 정확히 알아야 해요. 도커 컴포즈에서 빌드를 수행할 때 가장 중요한 요소는 빌드 컨텍스트와 빌드 옵션이에요. 빌드 컨텍스트는 도커 데몬이 빌드를 위해 참조할 수 있는 파일들의 범위예요. 이 범위가 너무 넓으면 불필요한 파일까지 모두 전송되어 빌드 속도가 처참하게 느려져요.

또한, build 옵션을 통해 Dockerfile의 위치, 사용할 인자(args), 타겟 스테이지 등을 동적으로 제어할 수 있어요. 이 옵션들을 코드화하여 관리하는 것이 자동화의 첫걸음이에요. 단순히 명령어를 나열하는 것이 아니라, 상황에 맞는 환경 변수를 주입하고 최적화된 경로를 지정하는 능력이 필요해요.

환경별 빌드 방식 비교

현재 여러분의 팀이 어떤 방식으로 배포를 진행하고 있는지 아래 표를 통해 확인해 보세요. 어떤 단계로 넘어가야 할지 판단하는 기준이 될 거예요.

대부분의 개발자는 수동 방식에서 스크립트 방식으로 넘어가는 단계에서 큰 효율을 느껴요. 하지만 진정한 의미의 운영 자동화를 달성하려면 CI/CD 파이프라인을 구축하여 사람이 개입할 여지를 최소화해야 해요.

실전! 빌드 자동화 파이프라인 설계하기

이제 이론을 넘어 실제로 어떻게 자동화를 구현하는지 단계별로 살펴볼게요. 단순히 명령어를 자동화하는 것을 넘어, 빌드 과정을 최적화하고 안정성을 높이는 데 집중해야 해요.

STEP 1. 빌드 컨텍스트 최적화로 속도 잡기

자동화의 첫 번째 단계는 빌드 시간을 단축하는 것이에요. 빌드가 느리면 CI/CD 파이프라인 전체가 지연되고, 이는 개발 생산성 저하로 이어져요. 가장 효과적인 방법은 .dockerignore 파일을 정교하게 작성하는 것이에요.

예를 들어, Node.js 프로젝트라면 node_modules나 로그 파일, 로컬 설정 파일(.env) 등은 빌드 컨텍스트에 포함될 필요가 없어요. 이런 파일들이 포함되면 도커 클라이언트가 서버로 데이터를 전송하는 시간이 길어지고, 빌드 과정에서 의도치 않은 파일이 이미지에 포함되어 보안 사고가 날 수도 있어요. 반드시 프로젝트에 필요한 소스 코드와 설정 파일만 포함되도록 관리해 주세요.

STEP 2. Build Args를 활용한 동적 환경 구성

개발(Dev), 테스트(Test), 운영(Prod) 환경은 각기 다른 설정이 필요해요. 매번 환경에 따라 docker-compose.yml을 새로 쓰는 것은 매우 비효율적이죠. 이때 사용할 수 있는 것이 바로 build args예요.

docker-compose.yml 파일 내에 다음과 같이 설정을 추가할 수 있어요.

이렇게 설정해 두면, 셸 스크립트에서 docker-compose build --build-arg APP_VERSION=1.1.0 처럼 명령어를 실행하여 이미지 빌드 시점에 값을 주입할 수 있어요. 이를 통해 하나의 Dockerfile로 다양한 환경에 대응하는 유연한 자동화 구조를 만들 수 있답니다.

STEP 3. 셸 스크립트로 빌드 로직 캡슐화하기

CI/CD 툴을 도입하기 전, 가장 먼저 해야 할 일은 자주 사용하는 명령어 조합을 셸 스크립트(.sh)로 만드는 것이에요. 단순한 명령어 나열이 아니라, 조건문과 에러 처리가 포함된 스크립트여야 해요.

다음은 빌드와 실행을 하나의 흐름으로 묶은 간단한 시나리오 스크립트 예시예요.

1. 기존 컨테이너 정지 및 제거
2. 새로운 이미지 빌드 (실패 시 중단)
3. 빌드 성공 시에만 새 컨테이너 실행
4. 실행 결과 로그 확인

이렇게 스크립트를 짜두면, 개발자는 ./deploy.sh prod 라는 짧은 명령 하나로 모든 과정을 안전하게 수행할 수 있어요. 스크립트 내부에서 빌드가 실패했을 때 exit 1을 호출하여 이후 단계가 진행되지 않도록 막는 것이 핵심이에요.

STEP 4. CI/CD 파이프라인(GitHub Actions) 연동

이제 스크립트를 클라우드로 옮길 차례예요. GitHub Actions를 예로 들면, 코드가 main 브랜치에 push될 때마다 자동으로 빌드가 시작되도록 설정할 수 있어요. 이때 앞에서 만든 빌드 옵션과 스크립트 로직을 그대로 활용하게 됩니다.

파이프라인 설계 시 고려해야 할 구체적인 흐름은 다음과 같아요.

• Checkout: 소스 코드를 가상 환경으로 가져오기
• Setup Docker: 도커 환경 설정 및 캐시 로드
• Build & Push: 컴포즈 옵션을 사용하여 빌드 후 레지스트리에 이미지 푸시
• Deploy: 운영 서버에 접속하여 새 이미지로 교체

이 과정에서 Docker Layer Caching을 활용하면 빌드 속도를 획기적으로 줄일 수 있어요. 변경되지 않은 레이어는 다시 빌드하지 않고 기존 캐시를 사용하게 만드는 설정이죠.

STEP 5. 멀티 스테이지 빌드로 이미지 경량화하기

마지막으로 자동화된 결과물이 가벼워야 해요. 빌드 과정에서 사용했던 컴파일러, 빌드 도구들은 최종 실행 이미지에 포함될 필요가 없어요. Multi-stage Build를 사용하여 빌드용 스테이지와 실행용 스테이지를 나누세요. 이렇게 하면 최종 이미지는 소스 코드와 실행 파일만 담게 되어 용량이 수백 MB에서 수십 MB로 줄어들고, 보안성도 크게 향상됩니다.

이 모든 단계를 거치면, 여러분의 배포 프로세스는 ‘사람의 손길’이 거의 필요 없는 완벽한 자동화 상태에 도달하게 돼요.

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

자동화를 구축하다 보면 예상치 못한 벽에 부딪히기 마련이에요. 가장 흔하게 겪는 문제들을 정리했으니, 비슷한 상황이라면 바로 적용해 보세요.

자주 하는 실수와 해결법

❌ 실수: 빌드 컨텍스트가 너무 커서 빌드 시간이 계속 늘어나요.
왜 발생하는가: .dockerignore 파일을 설정하지 않아 node_modules나 대용량 데이터 파일이 모두 도커 데몬으로 전송되기 때문이에요.
✅ 해결법: 프로젝트 루트에 .dockerignore를 생성하고, 불필요한 디렉토리와 파일을 명시적으로 제외하세요.

❌ 실수: CI/CD 환경에서 빌드 인자(args)가 전달되지 않아요.
왜 발생하는가: docker-compose.yml의 build 섹션에 args 정의가 누락되었거나, CI 설정 파일에서 환경 변수를 주입하지 않았기 때문이에요.
✅ 해결법: compose 파일에 args 항목을 선언하고, CI 도구의 환경 변수 설정(env)을 확인하세요.

❌ 실수: 빌드할 때마다 매번 모든 패키지를 새로 설치해요.
왜 발생하는가: Dockerfile 내의 레이어 캐시가 깨졌거나, 캐시를 유지하도록 하는 설정이 빠져 있기 때문이에요.
✅ 해결법: 패키지 설치 명령(npm install 등)을 소스 코드 복사(COPY .) 명령보다 앞 순서에 배치하여 캐시 효율을 높이세요.

❌ 실수: 자동 배포 후 서버가 작동하지 않아요.
왜 발생하는가: 빌드 자체는 성공했지만, 실행 시 필요한 환경 변수나 네트워크 설정이 누락되었을 가능성이 커요.
✅ 해결법: 배포 전 단계에서 컨테이너의 헬스체크(Healthcheck)를 수행하도록 구성하고, 실패 시 즉시 롤백하는 로직을 추가하세요.

❌ 실수: 빌드 과정에서 보안 민감 정보(API Key 등)가 노출돼요.
왜 발생하는가: 빌드 인자(build-arg)에 비밀번호나 키 값을 직접 넣었기 때문이에요.
✅ 해결법: 빌드 인자가 아닌 런타임 환경 변수(environment)를 사용하거나, Docker Secrets 기능을 활용하세요.

자주 묻는 질문

Q. 빌드 속도를 높이기 위한 가장 가성비 좋은 방법은 무엇인가요?

가장 먼저 .dockerignore를 통해 컨텍스트 크기를 줄이고, 그 다음으로는 Dockerfile의 레이어 순서를 최적화하여 캐시 활용도를 높이는 것이 가장 효과적이에요.

Q. 셸 스크립트와 CI/CD 툴 중 무엇을 먼저 공부해야 할까요?
규모가 작다면 셸 스크립트부터 시작하는 것을 추천해요. 로직을 직접 작성하며 자동화의 원리를 이해한 뒤, 이를 GitHub Actions 같은 전문 툴로 확장하는 것이 학습 곡선 측면에서 훨씬 유리해요.

Q. 컴포즈 빌드 옵션 자동화가 꼭 필요한 규모인가요?
혼자 하는 프로젝트라도 배포가 2회 이상 반복된다면 도입하는 것이 좋아요. 실수를 줄여주는 것만으로도 이미 충분한 가치가 있거든요.

Q. 멀티 스테이지 빌드를 쓰면 관리가 복잡해지지 않나요?
처음에는 Dockerfile이 길어져 복잡해 보일 수 있지만, 결과적으로 이미지가 가벼워지고 보안이 강화되므로 운영 측면에서는 훨씬 관리가 쉬워져요.

배포의 자유를 얻기 위한 다음 단계

지금까지 컴포즈 빌드 옵션 자동화의 기초부터 CI/CD 연동까지 살펴보았어요. 자동화는 한 번에 완성되는 것이 아니라, 작은 단위부터 차근차근 확장해 나가는 과정이에요. 처음부터 완벽한 파이프라인을 만들려 하기보다는, 지금 당장 나를 괴롭히는 반복 작업부터 하나씩 떼어내는 것이 중요해요.

오늘 바로 시작할 수 있는 실행 계획을 제안해 드릴게요.

• 오늘 할 일: 프로젝트 루트에 .dockerignore 파일을 만들고 불필요한 파일들을 등록해 보세요.
• 이번 주 할 일: 자주 쓰는 빌드 명령어를 담은 간단한 deploy.sh 파일을 만들어 보세요.
• 실행 직전 할 일: GitHub Actions나 GitLab CI를 활용해 자동화 파이프라인을 테스트해 보세요.

가장 자주 반복하는 명령어 하나부터 스크립트로 옮겨 보세요. 그 작은 시작이 여러분의 퇴근 시간을 앞당겨 줄 거예요. 효율적인 인프라 운영을 통해 더 가치 있는 코드 작성에 집중하시길 바랍니다.

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