[IT-방법] 컴포즈 build 옵션 자동화와 CI/CD 연동 – 배포 스트레스를 줄이는 실무 가이드

수동 배포의 한계와 자동화가 필요한 순간

금요일 오후 5시, 마지막 배포를 앞두고 손에 땀이 쥐어지는 경험을 해보셨나요? 터미널에 익숙한 명령어를 입력하지만, 손가락이 아주 미세하게 떨리는 그 순간이 있어요. “docker-compose build –build-arg VERSION=1.2.3 …” 이 긴 명령어를 입력하다가 오타 하나라도 내면 어떻게 될까요? 잘못된 버전이 빌드되거나, 빌드 인자가 누락되어 컨테이너가 실행되지 않는 상황은 개발자에게 큰 스트레스로 다가와요.

매번 동일한 빌드 옵션을 수동으로 타이핑하는 것은 단순한 귀찮음을 넘어 인적 오류(Human Error)를 유발하는 가장 큰 원인이에요. 특히 프로젝트 규모가 커지면서 빌드 컨텍스트가 복잡해지면, 어떤 인자를 넣어야 하는지 기억하는 것조차 힘들어지죠. 한두 번은 실수로 넘어가지만, 서비스가 운영 단계에 접어들면 단 한 번의 설정 오류가 서비스 전체의 중단으로 이어질 수 있어요.

이제는 단순히 명령어를 외워서 입력하는 단계를 지나야 해요. 컴포즈 build 옵션 자동화는 선택이 아니라 필수적인 생존 전략이에요. 빌드 과정을 기계에게 맡기고, 개발자는 로직과 서비스 품질에만 집중할 수 있는 환경을 만들어야 합니다.

이 글을 끝까지 읽고 나면 다음과 같은 문제를 해결할 수 있어요.

• 반복되는 긴 빌드 명령어를 스크립트 하나로 줄이는 법
• 환경별로 다른 빌드 인자를 안전하게 관리하는 법
• CI/CD 파이프라인에 빌드 과정을 녹여내는 실무 노하우
• 빌드 속도를 획기적으로 높이는 캐시 최적화 전략

자동화 시작 전 꼭 알아야 할 핵심 개념

자동화를 시작하기 전에 먼저 우리가 무엇을 자동화할 것인지 명확히 정의해야 해요. 무턱대고 스크립트부터 짜는 것이 아니라, 도커 컴포즈(Docker Compose)의 빌드 메커니즘을 정확히 이해하는 것이 첫걸음이에요.

빌드 컨텍스트와 옵션의 이해

가장 먼저 이해해야 할 개념은 빌드 컨텍스트(Build Context)예요. 도커가 이미지를 만들 때 참조하는 파일들의 범위인데, 이 범위가 너무 넓으면 빌드 속도가 느려지고 보안상 위험할 수 있어요. 또한, build-arg는 빌드 시점에 동적으로 값을 주입하는 아주 강력한 도구예요. 환경 변수와 비슷해 보이지만, 빌드 과정 중에만 유효하다는 차이점이 있죠.

자동화 방식 비교하기

자동화를 구현하는 방법은 여러 가지가 있어요. 어떤 방식을 선택하느냐에 따라 관리의 난이도와 확장성이 완전히 달라져요. 여러분의 현재 상황에 맞는 최적의 도구를 선택해 보세요.

단순히 개인 개발 환경에서만 사용한다면 쉘 스크립트나 Makefile이 적당하지만, 팀 단위로 운영하거나 지속적인 배포가 필요하다면 반드시 CI/CD 파이프라인을 구축하는 방향으로 가야 해요.

단계별 컴포즈 build 옵션 자동화 실행 전략

이제 본격적으로 자동화를 구현하는 구체적인 단계를 살펴볼게요. 이 과정은 단순히 명령어를 묶는 것이 아니라, 안정적이고 빠른 빌드 환경을 설계하는 과정이에요.

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

자동화의 첫 번째 핵심은 빌드 컨텍스트를 최소화하는 것이에요. 많은 개발자가 실수하는 부분 중 하나가 프로젝트 전체 폴더를 빌드 컨텍스트로 넘기는 거예요. 이렇게 하면 불필요한 파일들(예: .git, node_modules, 로그 파일)까지 도커 데몬으로 전송되어 빌드 속도가 엄청나게 느려져요.

이를 해결하기 위해 반드시 .dockerignore 파일을 작성해야 해요. Git의 .gitignore와 유사한 방식으로, 빌드에 필요 없는 파일들을 명시적으로 제외해 주세요. 예를 들어, 테스트 결과 파일이나 로컬 설정 파일들을 제외하면 컨텍스트 크기가 줄어들어 빌드 시작 전 파일 전송 시간이 단축돼요. 이것만으로도 빌드 효율이 20~30% 이상 개선되는 경우를 흔히 볼 수 있어요.

STEP 2. 환경 변수 분리를 위한 .env 파일 설계

빌드 옵션 중 가장 자주 바뀌는 것이 바로 build-arg예요. 서비스 버전, API 엔드포인트, 환경 이름(dev, staging, prod) 등이 대표적이죠. 이를 매번 명령어에 직접 입력하는 것은 자동화의 적이에요.

가장 권장하는 방법은 환경별 .env 파일을 미리 만들어 두는 것이에요. 예를 들어 `.env.dev`, `.env.prod` 파일을 만들고, 컴포즈 실행 시점에 이 파일을 참조하게 만드세요. 이렇게 하면 컴포즈 파일 안에서는 변수명만 써두고, 실제 값은 파일에서 가져오게 되어 명령어가 매우 단순해져요.

STEP 3. 쉘 스크립트를 활용한 빌드 및 실행 워크플로우

이제 흩어져 있는 명령어를 하나로 묶을 차례예요. 단순히 명령어들을 나열하는 것이 아니라, 에러 처리가 포함된 똑똑한 스크립트를 짜야 해요. 쉘 스크립트 상단에 set -e를 추가하면, 명령어 실행 중 하나라도 실패했을 때 즉시 중단되므로 잘못된 상태로 배포가 이어지는 것을 막을 수 있어요.

효율적인 스크립트 구성을 위한 시나리오를 예로 들어볼게요. 스크립트는 다음과 같은 순서로 작동하도록 설계하는 것이 좋아요.

1. 현재 Git 브랜치 확인 및 최신 코드 가져오기
2. 사용할 환경 변수 파일(.env) 로드
3. 기존에 실행 중인 컨테이너 중지 및 제거 (필요 시)
4. docker-compose build 실행 (build-arg 포함)
5. docker-compose up -d 실행
6. 컨테이너 상태 및 헬스 체크(Health Check) 수행

이렇게 구성된 스크립트는 단 한 줄의 실행으로 복잡한 빌드 과정을 안전하게 완료해 줍니다. 이제 개발자는 터미널에 ./deploy.sh prod라고만 치면 되는 것이죠.

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

스크립트가 로컬 환경을 위한 자동화라면, CI/CD는 팀 전체를 위한 자동화예요. GitHub Actions를 사용한다면, 코드가 메인 브랜치에 푸시될 때 자동으로 빌드가 시작되도록 설정할 수 있어요. 이때 가장 중요한 것은 보안이에요. API 키나 데이터베이스 비밀번호 같은 민감한 정보는 절대로 스크립트나 .env 파일에 직접 적어서 커밋하면 안 돼요.

대신 GitHub의 Secrets 기능을 사용하세요. GitHub Actions 워크플로우 파일 내에서 `${{ secrets.MY_API_KEY }}`와 같은 방식으로 호출하면, 빌드 시점에 안전하게 환경 변수로 주입할 수 있어요. 이 과정을 통해 개발자는 코드를 푸시하기만 하면 빌드부터 배포까지의 전 과정을 시스템에 맡길 수 있게 됩니다.

STEP 5. 빌드 캐시 최적화로 속도 잡기

자동화가 잘 되어 있어도 빌드 시간이 10분, 20분씩 걸린다면 개발 생산성은 떨어질 수밖에 없어요. 이를 위해 캐시 활용 전략을 세워야 해요. 도커는 레이어 단위로 캐시를 저장하는데, Dockerfile의 구조를 어떻게 잡느냐에 따라 캐시 적중률이 완전히 달라져요.

자주 바뀌지 않는 패키지 설치 단계(예: npm install, pip install)를 Dockerfile의 상단에 배치하고, 자주 바뀌는 소스 코드 복사 단계는 하단에 배치하세요. 또한, CI 환경에서는 이전 빌드에서 생성된 이미지를 –cache-from 옵션으로 불러와서 재사용하는 설정이 필수적이에요. 이렇게 하면 매번 모든 라이브러리를 새로 받는 낭비를 막고, 빌드 시간을 몇 분 단위로 단축할 수 있어요.

자주 하는 실수와 해결법

자동화를 구축하다 보면 예상치 못한 함정에 빠지기 쉬워요. 실무에서 가장 빈번하게 발생하는 문제들을 정리해 보았습니다.

• ❌ 실수: .dockerignore를 설정하지 않아 빌드가 너무 느림
  → 왜 발생하는가: 컨테이너 이미지에 불필요한 로컬 데이터(node_modules, .git 등)가 포함되어 전송 시간이 길어집니다.
  ✅ 해결법: 프로젝트 루트에 .dockerignore 파일을 만들고 제외할 목록을 철저히 관리하세요.
• ❌ 실수: build-arg로 민감한 정보를 주입함
  → 왜 발생하는가: build-arg는 이미지 레이어에 기록되므로, 누구나 이미지를 확인하면 값을 볼 수 있어 보안에 매우 취약합니다.
  ✅ 해결법: 민감한 정보는 build-arg 대신 실행 시점에 환경 변수(Runtime Environment Variable)로 넘기거나 Secret Management 도구를 사용하세요.
• ❌ 실수: 쉘 스크립트에서 에러 처리를 누락함
  → 왜 발생하는가: 빌드 중 에러가 났음에도 스크립트가 계속 진행되어, 깨진 이미지가 배포되는 상황이 발생합니다.
  ✅ 해결법: 스크립트 상단에 set -e를 반드시 추가하여 에러 발생 시 즉시 중단되도록 만드세요.
• ❌ 실수: 환경별 .env 파일 경로를 잘못 지정함
  → 왜 발생하는가: 자동화 도구가 파일을 찾지 못해 기본값으로 빌드되거나 설정이 누락되어 런타임 오류가 발생합니다.
  ✅ 해결법: 스크립트 내에서 파일 존재 여부를 먼저 체크(if [ -f .env.prod ])하는 로직을 포함하세요.
• ❌ 실수: 캐시 오염(Cache Pollution) 현상
  → 왜 발생하는가: 이전 빌드의 잔재가 남아 새 설정이 반영되지 않는 경우가 있습니다.
  ✅ 해결법: 가끔씩 --no-cache 옵션을 사용하여 깨끗한 상태에서 빌드 테스트를 진행해 보세요.

자주 묻는 질문

Q. 컴포즈 build 옵션과 도커 빌드 옵션은 무엇이 다른가요?

도커 빌드 명령어가 단일 이미지를 만드는 데 집중한다면, 컴포즈 빌드는 여러 개의 서비스가 얽힌 전체 시스템의 빌드 관계를 정의해요. 컴포즈를 사용하면 여러 서비스에 공통된 build-arg를 한 번에 전달하거나 서비스 간 의존성을 고려한 순차 빌드가 훨씬 쉬워집니다.

Q. GitHub Actions에서 build-arg를 전달할 때 가장 안전한 방법은 무엇인가요?
환경 변수로 저장된 값을 워크플로우 파일의 env 섹션에서 읽어온 뒤, docker-compose build 명령의 인자로 전달하는 방식이 가장 일반적이고 안전해요.

Q. 빌드 속도를 높이기 위해 멀티 스테이지 빌드를 꼭 써야 하나요?
네, 강력히 추천해요. 빌드에만 필요한 도구(컴파일러, SDK 등)와 실제 실행에 필요한 결과물(런타임)을 분리하면 최종 이미지 용량이 줄어들 뿐만 아니라, 레이어 캐시 효율도 극대화할 수 있습니다.

Q. .env 파일을 깃허브에 올려도 괜찮을까요?
절대 안 됩니다. 설정 파일에 비밀번호나 API 키가 포함되어 있다면 보안 사고로 이어져요. 설정 파일의 템플릿인 .env.example만 공유하고, 실제 값은 서버나 CI 도구의 비밀 설정 기능을 활용하세요.

효율적인 컨테이너 운영을 위한 다음 단계

지금까지 컴포즈 build 옵션을 자동화하여 배포의 안정성과 효율성을 높이는 방법을 알아보았어요. 처음에는 스크립트를 짜는 것이 번거롭게 느껴질 수 있지만, 한 번 구축해 두면 여러분의 퇴근 시간이 훨씬 빨라질 거예요.

자동화는 완성형이 아니라 진화형이에요. 오늘 당장 가장 자주 반복하는 긴 명령어 하나를 쉘 스크립트로 만드는 것부터 시작해 보세요. 작은 자동화가 모여 거대한 데브옵스(DevOps) 환경을 만듭니다.

앞으로 나아갈 로드맵

• 오늘 할 일: 현재 사용하는 빌드 명령어를 메모장에 모두 적어보고, 불필요한 파일이 포함되어 있는지 확인하기
• 이번 주 할 일: 간단한 쉘 스크립트를 작성하여 로컬 환경에서 빌드와 실행을 한 번에 수행해 보기
• 실행 직전 할 일: GitHub Actions를 사용하여 코드가 푸시될 때 자동으로 빌드가 돌아가는지 테스트하기

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