[IT-방법] 컴포즈 build 옵션 자동화와 CI/CD 연동 – 배포 과정을 자동화하여 운영 효율 높이기

반복되는 배포 명령어가 만드는 비효율의 늪

코드 한 줄을 수정했을 뿐인데, 터미널을 열고 docker-compose build를 입력한 뒤 빌드가 끝나기만을 하릴없이 기다리고 계신가요? 가끔은 빌드 컨텍스트가 너무 커서 빌드 속도가 말도 안 되게 느려지거나, 환경 변수를 하나 빼먹어서 배포에 실패하는 경험을 해보셨을 거예요. 이런 사소한 실수들이 쌓이면 결국 배포는 공포스러운 작업이 되고, 개발자는 정작 중요한 기능 구현보다 터미널 창을 지키는 데 더 많은 시간을 쓰게 돼요.

수동 배포는 단순히 귀찮은 문제가 아니에요. 사람이 개입하는 순간 실수가 발생할 확률은 기하급수적으로 높아지죠. 빌드 옵션을 잘못 설정하거나, 운영 환경에 맞지 않는 인자를 전달하는 실수는 서비스 장애로 직결될 수 있어요. 이제는 사람이 명령어를 치는 시대가 아니라, 시스템이 알아서 빌드하고 배포하는 환경을 만들어야 할 때예요.

이 글을 통해 여러분은 더 이상 배포 버튼을 누르며 기도하지 않아도 되는 환경을 구축할 수 있어요. 컴포즈의 빌드 옵션을 어떻게 자동화 스크립트에 녹여내는지, 그리고 이를 어떻게 안정적인 CI/CD 파이프라인으로 연결하는지 실무적인 관점에서 아주 자세히 다뤄볼게요.

자동화 이전에 반드시 정립해야 할 빌드 기본기

무작정 스크립트를 짜기 전에 우리가 제어해야 할 대상이 무엇인지 명확히 알아야 해요. 도커 컴포즈에서 빌드를 자동화한다는 것은 결국 컴포즈 파일 내의 build 섹션을 어떻게 변수화하고 제어할 것인가의 문제로 귀결돼요. 빌드 컨텍스트가 무엇인지, 어떤 옵션이 자동화의 핵심인지를 먼저 이해해야 해요.

빌드 컨텍스트는 도커 데몬이 빌드 과정에서 접근할 수 있는 파일들의 범위예요. 이 범위가 너무 넓으면 불필요한 파일까지 모두 전송하느라 빌드 속도가 느려지고, 반대로 너무 좁으면 필요한 설정 파일을 찾지 못해 에러가 발생하죠. 따라서 자동화의 첫 단추는 이 컨텍스트를 정확하게 지정하는 것부터 시작해요.

또한, 빌드 과정에서 주입되는 인자인 build args를 어떻게 관리할지도 결정해야 해요. 개발 환경과 운영 환경의 설정이 다르기 때문에, 이를 코드에 직접 적지 않고 외부에서 주입받을 수 있는 구조를 설계하는 것이 자동화의 핵심이에요.

자동화 전략 선택을 위한 기준

현재 팀의 규모나 배포 빈도에 따라 어떤 수준의 자동화를 적용할지 결정해야 해요. 아래 표를 보고 여러분의 상황에 맞는 최적의 경로를 선택해 보세요.

성공적인 빌드 자동화를 위한 5단계 실행 로드맵

이제 본격적으로 자동화의 설계도를 그려볼게요. 단순히 명령어를 옮기는 것이 아니라, 환경의 변화에 유연하게 대응할 수 있는 견고한 구조를 만드는 것이 목표예요. 각 단계를 차근차근 따라오시면 여러분의 배포 프로세스가 완전히 달라질 거예요.

STEP 1. 빌드 컨텍스트 최적화와 .dockerignore 활용

자동화의 첫 번째 핵심은 빌드 속도를 결정짓는 컨텍스트를 다이어트하는 것이에요. 많은 개발자가 실수하는 부분 중 하나가 프로젝트 루트 디렉토리를 통째로 빌드 컨텍스트로 사용하는 것이에요. 이렇게 하면 .git 폴더, 로컬 로그 파일, node_modules 같은 거대한 디렉토리가 모두 도커 데몬으로 전송되어 빌드 시간이 기하급수적으로 늘어나요.

이를 해결하기 위해 반드시 .dockerignore 파일을 작성해야 해요. 빌드에 필요 없는 파일들을 명시적으로 제외하면 전송 데이터 양이 줄어들고, 캐시 효율도 높아져요. 예를 들어, 로그 파일, 로컬 설정 파일, 테스트 결과물, 대용량 바이너리 파일 등을 포함시켜 보세요. 이것만으로도 빌드 속도가 2배 이상 빨라지는 마법을 경험할 수 있어요.

STEP 2. 환경 변수를 이용한 build args 동적 제어

운영 환경에서는 특정 라이브러리 버전을 사용해야 하고, 개발 환경에서는 디버깅 도구가 포함되어야 할 때가 있죠? 이럴 때마다 컴포즈 파일을 새로 만드는 것은 매우 비효율적이에요. 정답은 build args와 환경 변수를 조합하는 것이에요.

컴포즈 파일의 build 섹션 안에 args 항목을 만들고, 그 값을 변수로 처리하세요. 그러면 실행 시점에 –build-arg 옵션을 통해 원하는 값을 주입할 수 있어요. 예를 들어, 앱의 버전을 빌드 시점에 주입하거나, 특정 API 엔드포인트를 환경별로 다르게 설정하는 작업이 매우 쉬워져요. 이는 코드의 수정 없이 설정만으로 배포 환경을 제어할 수 있게 해준다는 점에서 매우 강력한 자동화 도구가 돼요.

STEP 3. 자동화 쉘 스크립트 구축하기

이제 개별적인 명령어를 하나의 흐름으로 묶어줄 스크립트를 만들 차례예요. 단순히 docker-compose build를 넣는 것에 그치지 말고, 실행 전후의 검증 로직을 포함해야 해요. 좋은 자동화 스크립트는 다음과 같은 흐름을 가져야 해요.

• 환경 변수 파일(.env)의 존재 여부 확인
• 기존에 생성된 미사용 이미지 정리(prune)
• 컴포즈 빌드 명령 실행 (에러 핸들링 포함)
• 빌드 성공 시 컨테이너 재시작 및 상태 확인

이렇게 작성된 스크립트는 개발자가 실수로 잘못된 옵션을 넣는 것을 원천 차단하고, 항상 동일한 절차로 빌드가 진행됨을 보장해요. 스크립트 파일은 프로젝트 내의 scripts/ 디렉토리에 관리하여 팀원 모두가 공유할 수 있도록 하세요.

STEP 4. CI/CD 파이프라인과의 완전한 통합

스크립트가 준비되었다면, 이제 이를 클라우드 환경으로 옮겨야 해요. GitHub Actions나 GitLab CI 같은 도구를 사용하여, 코드가 메인 브랜치에 푸시될 때마다 자동으로 빌드가 시작되도록 구성하세요. 이때 가장 중요한 것은 빌드 결과물인 이미지를 레지스트리에 저장하고 배포하는 과정의 자동화예요.

CI/CD 파이프라인 설계 시에는 반드시 빌드 단계와 배포 단계를 분리하세요. 빌드 단계에서는 이미지를 만들고 태그를 붙여 레지스트리에 푸시(Push)하고, 배포 단계에서는 그 이미지를 가져와 컨테이너를 띄우는 방식이에요. 이렇게 하면 빌드 과정에서 발생한 문제가 실제 운영 환경의 컨테이너 실행에 영향을 주는 것을 방지할 수 있어요. 또한, 파이프라인에서 제공하는 캐시 기능을 활용하면 매번 처음부터 빌드할 필요 없이 변경된 부분만 빠르게 빌드할 수 있어요.

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

마지막 단계는 완성된 자동화 프로세스의 결과물을 최상으로 만드는 것이에요. 자동화된 파이프라인이 생성하는 이미지가 너무 크다면, 배포 속도가 느려지고 스토리지 비용이 증가해요. 이를 해결하기 위해 멀티 스테이지 빌드(Multi-stage Build)를 반드시 적용하세요.

빌드할 때 필요한 컴파일러나 라이브러리는 첫 번째 스테이지에서 사용하고, 최종 이미지에는 실행에 꼭 필요한 결과물만 담는 방식이에요. 자동화 스크립트가 이 멀티 스테이지 빌드를 수행하도록 설정해두면, 배포 환경에는 아주 가볍고 보안성이 높은 이미지만 전달돼요. 이는 배포 성공률을 높일 뿐만 아니라 컨테이너 운영의 효율성을 극대화하는 핵심 전략이에요.

자주 하는 실수와 해결법

자동화 시스템을 구축하다 보면 예상치 못한 곳에서 벽에 부딪히곤 해요. 가장 흔하게 발생하는 실수들을 정리했으니, 여러분의 설정과 비교해 보세요.

❌ 실수: .dockerignore를 만들지 않아 빌드가 너무 느려짐
👉 왜 발생하는가: 프로젝트의 모든 파일(특히 .git이나 대용량 로그)이 빌드 컨텍스트로 포함되어 네트워크 전송량이 늘어나기 때문이에요.
✅ 해결법: 반드시 .dockerignore 파일을 생성하고 불필요한 폴더를 명시하세요.

❌ 실수: 빌드 인자(build args)를 Dockerfile에 하드코딩함
👉 왜 발생하는가: 환경별로 다른 값을 넣기 위해 매번 파일을 수정하면 자동화의 의미가 사라지기 때문이에요.
✅ 해결법: 컴포즈 파일에서 변수를 선언하고, 실행 시점에 주입받도록 구조를 바꾸세요.

❌ 실수: 레이어 캐시를 제대로 활용하지 못해 매번 전체 빌드 수행
👉 왜 발생하는가: Dockerfile 내의 명령 순서가 비효율적이거나, 변경이 잦은 파일을 상단에 두었기 때문이에요.
✅ 해결법: 변경이 적은 패키지 설치 명령을 상단에, 소스 코드 복사 명령을 하단에 배치하세요.

❌ 실수: CI/CD 과정에서 보안 비밀번호(Secrets)를 노출함
👉 왜 발생하는가: API 키나 DB 비밀번호를 컴포즈 파일이나 Dockerfile에 직접 적었기 때문이에요.
✅ 해결법: CI/CD 도구의 Secret 기능을 사용하여 환경 변수로 주입하세요.

❌ 실수: 빌드 성공 후 컨테이너 상태를 검증하지 않음
👉 왜 발생하는가: 이미지만 빌드되었다고 해서 서비스가 정상 작동한다는 보장이 없기 때문이에요.
✅ 해결법: 스크립트 마지막에 docker inspect나 curl 명령어로 서비스 헬스체크 단계를 추가하세요.

자주 묻는 질문

Q. 빌드 속도를 높이는 가장 효과적인 방법 하나만 꼽는다면 무엇인가요?

가장 즉각적인 효과를 볼 수 있는 것은 .dockerignore를 통해 빌드 컨텍스트의 크기를 줄이는 것이에요. 그 다음으로는 Dockerfile의 레이어 캐시를 효율적으로 사용하도록 명령 순서를 최적화하는 것이 중요해요.

Q. 개발용과 운영용 컴포즈 파일을 따로 관리해야 하나요?

파일을 완전히 분리하는 것보다, 기본이 되는 docker-compose.yml을 두고 환경별로 차이가 나는 부분만 docker-compose.override.yml이나 환경 변수를 통해 덮어쓰는 방식이 관리 측면에서 훨씬 유리해요.

Q. 빌드 과정에서 에러가 나면 어떻게 자동으로 롤백하나요?

CI/CD 파이프라인에서 빌드나 배포 단계가 실패하면 다음 단계(실제 컨테이너 교체)로 넘어가지 않도록 설정해야 해요. 이미 운영 중인 컨테이너를 건드리지 않은 상태에서 에러를 감지하고 알림을 보내는 것이 가장 기본적인 롤백 전략이에요.

Q. build args와 환경 변수의 차이가 정확히 무엇인가요?

build args는 이미지를 만드는 과정(빌드 타임)에 필요한 값이고, 환경 변수(environment)는 이미지가 만들어진 후 컨테이너가 실행될 때(런타임) 필요한 값이에요. 이 둘을 구분해서 사용해야 효율적인 설계가 가능해요.

Q. 로컬에서 빌드한 이미지를 서버로 옮기는 가장 좋은 방법은 무엇인가요?

로컬에서 직접 옮기기보다는, 로컬에서는 빌드 테스트만 하고 실제 빌드는 CI/CD 서버가 수행하여 생성된 이미지를 이미지 레지스트리(Docker Hub, ECR 등)를 통해 서버가 내려받도록 하는 것이 가장 표준적이고 안전해요.

이제 배포의 스트레스에서 벗어나 개발에만 집중하세요

지금까지 컴포즈 빌드 옵션을 자동화하고 이를 안정적인 파이프라인으로 연결하는 핵심 전략들을 살펴보았어요. 자동화는 단순히 명령어를 줄이는 과정이 아니라, 서비스의 안정성을 확보하고 개발자의 정신 건강을 지키는 필수적인 투자예요.

한꺼번에 모든 것을 바꾸려고 하면 오히려 혼란이 올 수 있어요. 가장 먼저 여러분이 매일 반복하는 명령어 하나부터 스크립트로 옮기는 것부터 시작해 보세요. 작은 자동화가 모여 거대한 데브옵스 문화의 토대가 됩니다.

성장을 위한 다음 단계

• 오늘 할 일: 프로젝트 루트에 .dockerignore 파일을 만들고 불필요한 파일 제외하기
• 이번 주 할 일: 빌드 인자를 환경 변수로 처리하는 쉘 스크립트 작성해 보기
• 실행 직전 할 일: GitHub Actions나 GitLab CI의 기본 튜토리얼 따라 해 보기

더 깊이 있는 컨테이너 활용법이 궁금하시다면, 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드를 함께 읽어보시는 것을 추천드려요. 여러분의 성공적인 자동화를 응원해요!