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

매일 반복되는 빌드와 배포, 언제까지 수동으로 하실 건가요?

금요일 퇴근 직전, 마지막 코드를 반영하기 위해 터미널을 열고 docker-compose build 명령어를 입력하는 순간을 떠올려 보세요. 빌드가 진행되는 동안 커피 한 잔을 마시며 초조하게 화면을 바라보다가, 갑자기 예상치 못한 빌드 컨텍스트 오류나 캐시 문제로 빌드가 실패하면 눈앞이 캄캄해지곤 해요.

단순히 명령어를 한 번 입력하는 것이 문제가 아니에요. 개발 환경과 운영 환경의 차이 때문에 발생하는 빌드 옵션의 불일치, 매번 수동으로 관리해야 하는 환경 변수, 그리고 배포 직후 서비스에 문제가 생겼을 때 즉시 되돌릴 수 없는 불안함이 우리를 괴롭히지요. 이러한 반복적인 작업은 개발자의 집중력을 갉아먹고 결국 치명적인 운영 실수를 유발하는 원인이 돼요.

이제는 컴포즈 build 옵션 자동화를 통해 이런 굴레에서 벗어나야 할 때예요. 단순히 명령어를 대신 실행해 주는 것을 넘어, 빌드 컨텍스트를 최적화하고 CI/CD 파이프라인에 녹여내어 ‘사람의 손길이 닿지 않아도 안전하게 배포되는 환경’을 만드는 것이 이 글의 목표예요.

이번 글에서는 다음과 같은 내용을 깊이 있게 다뤄요.

• 빌드 속도와 용량을 결정짓는 빌드 컨텍스트 최적화 전략
• 다양한 상황에 대응하는 컴포즈 build 옵션 활용법
• CI/CD 파이프라인을 통한 배포 자동화 설계 단계
• 배포 실패 시 서비스를 보호하는 자동 롤백 전략

자동화 시스템 구축 전 반드시 점검해야 할 핵심 요소

무작정 자동화 스크립트를 짜기 시작하면 오히려 더 큰 혼란에 빠질 수 있어요. 자동화는 기존의 수동 프로세스를 완벽하게 이해하고, 그 과정에서 발생하는 변수를 통제할 수 있을 때 비로소 빛을 발하기 때문이에요. 본격적인 구축에 앞서 현재 여러분의 환경이 어떤 상태인지 점검하는 과정이 꼭 필요해요.

가장 먼저 살펴봐야 할 것은 빌드 컨텍스트(Build Context)의 크기예요. 도커 엔진으로 전달되는 파일의 양이 너무 많으면 빌드 시작 전부터 네트워크 부하가 발생하고 시간이 지체돼요. 또한, 사용 중인 CI/CD 도구가 도커 데몬에 접근할 수 있는 권한을 가지고 있는지도 확인해야 해요.

다음은 자동화 수준에 따른 비교표예요. 현재 여러분의 팀이 어느 단계에 있는지, 혹은 어느 단계로 나아가야 할지 판단하는 기준으로 삼아보세요.

어떤 단계를 선택하든 중요한 것은 재현 가능성(Reproducibility)이에요. 누가 언제 실행하더라도 동일한 환경에서 동일한 이미지가 생성될 수 있도록 설계해야 해요. 이를 위해 환경 변수는 외부 파일로 분리하고, 빌드 시 사용되는 인자(Args)들을 명확히 문서화해두는 것이 좋습니다.

효율적인 빌드 자동화를 위한 5단계 실행 전략

이제 본격적으로 실무에 적용 가능한 자동화 단계를 살펴볼게요. 단계별로 차근차근 적용해 나가면, 어느샌가 배포 버튼 하나로 모든 과정이 끝나는 경험을 하시게 될 거예요.

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

빌드 속도를 결정하는 첫 번째 단추는 바로 빌드 컨텍스트를 얼마나 가볍게 만드느냐에 달려 있어요. 많은 개발자가 실수하는 부분 중 하나가 프로젝트 루트 디렉토리를 통째로 빌드 컨텍스트로 넘기는 것이에요. 이 과정에서 용량이 큰 로그 파일, 로컬 데이터베이스 파일, 혹은 node_modules와 같은 의존성 폴더가 도커 데몬으로 전송되면서 빌드 시간이 기하급수적으로 늘어나게 돼요.

이를 해결하기 위해 반드시 .dockerignore 파일을 작성하세요. 불필요한 파일을 제외하는 것만으로도 빌드 시작 시간을 수십 초에서 수 분까지 단축할 수 있어요. 제외해야 할 대표적인 항목들은 다음과 같아요.

• .git: 버전 관리 이력은 이미지에 필요하지 않아요.
• node_modules 또는 venv: 빌드 과정에서 다시 설치하는 것이 안전해요.
• *.log: 운영 중에 쌓인 로그는 이미지 크기만 키울 뿐이에요.

STEP 2. 컴포즈 build 옵션 전략적으로 활용하기

도커 컴포즈 파일의 build 섹션에는 다양한 옵션을 넣을 수 있어요. 자동화할 때 이 옵션들을 제대로 써야 빌드 효율이 극대화돼요. 특히 다중 단계 빌드(Multi-stage Build)와 결합하면 아주 강력해져요.

가장 유용한 옵션은 args와 target이에요. 예를 들어, 개발용 이미지와 운영용 이미지를 하나의 Dockerfile로 관리하면서, 컴포즈 파일에서 target: production 옵션을 주어 운영 환경에 최적화된 가벼운 이미지 단계까지만 빌드하도록 설정할 수 있어요. 또한 cache_from 옵션을 활용하면 원격 저장소에 있는 이미지를 캐시로 사용하여 빌드 시간을 획기적으로 줄일 수 있답니다.

STEP 3. 쉘 스크립트로 워크플로우 캡슐화하기

CI/CD로 넘어가기 전, 중간 단계로 배포 스크립트를 만드는 과정을 추천해요. 매번 길고 복잡한 명령어를 입력하는 대신, 자주 사용하는 명령어를 하나의 스크립트 파일로 묶어두는 것이죠.

간단한 스크립트 예시는 다음과 같아요. 이 스크립트는 빌드, 테스트, 그리고 컨테이너 재시작까지를 하나의 흐름으로 만들어줘요.

#!/bin/bash
set -e

echo "🚀 빌드 프로세스를 시작합니다..."
docker-compose build --no-cache

echo "🧪 테스트를 실행합니다..."
docker-compose run --rm app npm test

echo "🚢 컨테이너를 업데이트합니다..."
docker-compose up -d

echo "✅ 배포가 성공적으로 완료되었습니다!"

STEP 4. CI/CD 파이프라인에 자동 빌드 통합하기

이제 스크립트를 GitHub Actions나 GitLab CI 같은 전문 도구에 올릴 차례예요. 파이프라인 설계 시 핵심은 격리된 환경에서 빌드를 수행하는 것이에요. 개발자의 로컬 PC 상태에 의존하지 않고, 깨끗한 러너(Runner) 환경에서 빌드가 일어남을 보장해야 해요.

파이프라인 단계는 보통 다음과 같은 순서로 설계해요. 먼저 코드가 푸시되면 린트(Lint) 검사로 문법 오류를 잡고, 이어서 빌드 단계를 거쳐 이미지를 생성해요. 생성된 이미지는 바로 서버에 올리는 것이 아니라, 스테이징 환경에 먼저 배포하여 자동화된 테스트를 거쳐야 해요. 이 모든 과정이 통과되었을 때만 운영 환경으로 이미지가 전달되는 구조를 만들어야 안전해요.

STEP 5. 배포 검증(Health Check) 단계 추가하기

빌드가 성공했다고 해서 배포가 성공한 것은 아니에요. 컨테이너는 떴지만 내부 애플리케이션이 에러로 인해 계속 재시작되는 상황이 발생할 수 있기 때문이죠. 이를 방지하기 위해 컴포즈 파일에 healthcheck 설정을 반드시 포함해야 해요.

애플리케이션의 특정 엔드포인트(예: /health)를 주기적으로 체크하도록 설정하면, 도커는 서비스가 실제로 요청을 처리할 수 있는 상태인지 판단할 수 있어요. 만약 헬스 체크가 실패하면, 배포 파이프라인은 즉시 실패로 간주하고 다음 단계인 롤백으로 넘어가도록 설계할 수 있답니다.

자주 하는 실수와 해결법

자동화를 구축하다 보면 예상치 못한 난관에 부딪히기 마련이에요. 실무에서 가장 빈번하게 발생하는 실수들과 그 해결책을 정리해 두었으니, 문제가 생기면 즉시 확인해 보세요.

• ❌ .dockerignore를 작성하지 않아 빌드 속도가 매우 느려지는 경우
  → 왜 발생하는가: 수백 메가바이트의 불필요한 파일이 빌드 컨텍스트로 전송되기 때문이에요.
  ✅ 해결법: 프로젝트 루트에 .dockerignore 파일을 만들고 node_modules, .git, logs 등을 반드시 제외하세요.
• ❌ 빌드 아규먼트(Build Args)를 하드코딩하는 경우
  → 왜 발생하는가: 환경마다 다른 설정값을 코드에 직접 써넣었기 때문이에요.
  ✅ 해결법: .env 파일을 사용하거나 CI/CD 도구의 Secret 기능을 통해 환경 변수를 주입하세요.
• ❌ 캐시를 과도하게 사용하여 이전 코드가 반영되지 않는 경우
  → 왜 발생하는가: 도커의 레이어 캐싱이 의도치 않게 작동했기 때문이에요.
  ✅ 해결법: 코드 변경이 잦은 단계 직전에는 빌드 옵션을 조정하거나, 필요시 –no-cache를 사용하세요.
• ❌ 컨테이너 실행 후 상태를 확인하지 않고 배포를 종료하는 경우
  → 왜 발생하는가: 컨테이너가 떴지만 내부 로직 에러로 ‘CrashLoopBackOff’ 상태에 빠졌기 때문이에요.
  ✅ 해결법: docker-compose.yml에 healthcheck를 설정하고, 파이프라인에서 이를 검증하는 단계를 넣으세요.
• ❌ 멀티 스테이지 빌드를 활용하지 않아 이미지 용량이 너무 큰 경우
  → 왜 발생하는가: 빌드 도구와 소스 코드가 모두 포함된 무거운 이미지를 그대로 사용하기 때문이에요.
  ✅ 해결법: 빌드용 단계와 실행용 단계를 나누어 최종 이미지에는 실행 파일만 남도록 설계하세요.

자주 묻는 질문

Q. 빌드 속도를 가장 빠르게 만드는 방법은 무엇인가요?

가장 효과적인 방법은 빌드 컨텍스트를 최소화하는 것과 레이어 캐싱을 잘 활용하는 것이에요. 자주 바뀌는 파일(소스 코드)은 Dockerfile의 뒷부분에 배치하고, 거의 바뀌지 않는 설정이나 라이브러리 설치 과정은 앞부분에 배치하여 도커가 기존 캐시를 최대한 재사용하도록 만들어야 해요.

Q. CI/CD 환경에서 도커 캐시를 어떻게 유지하나요?

대부분의 CI 환경은 매번 깨끗한 상태에서 시작하기 때문에 캐시가 사라져요. 이때는 빌드한 이미지를 레지스트리(Docker Hub, ECR 등)에 저장해 두었다가, 빌드할 때 --cache-from 옵션을 사용하여 이전 이미지를 불러오도록 설정하면 돼요.

Q. docker-compose build와 docker-compose up –build의 차이는 무엇인가요?

build 명령어는 이미지만 생성하고 멈추지만, up –build는 이미지를 새로 만든 뒤 즉시 컨테이너를 생성하고 실행까지 완료해요. 자동화 스크립트에서는 빌드와 실행 단계를 명확히 분리하는 것이 디버깅에 유리해요.

Q. 빌드 중에 에러가 나면 이전 버전으로 자동 복구할 수 있나요?

네, 가능해요. CI/CD 파이프라인 설계 시 빌드/테스트 단계가 실패하면 배포 단계(up)로 넘어가지 않도록 막고, 이미 배포된 상태에서 헬스 체크가 실패할 경우 이전 이미지 태그로 다시 배포하는 롤백 스크립트를 실행하도록 구성하면 돼요.

Q. 환경 변수를 관리하는 가장 안전한 방법은 무엇인가요?

코드 내에 저장하는 것은 절대 금물이에요! 로컬에서는 .env 파일을 사용하되, 운영 환경에서는 GitHub Secrets나 AWS Secrets Manager 같은 보안 관리 도구를 통해 주입하는 것이 정석이에요.

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

지금까지 컴포즈 build 옵션 자동화와 CI/CD 연동을 위한 핵심 전략들을 살펴보았어요. 자동화는 한 번 구축하기까지 공수가 들지만, 일단 완성되면 여러분의 퇴근 시간을 앞당겨주고 심리적인 안정감을 가져다줄 거예요.

자동화는 한꺼번에 모든 것을 바꾸려 하지 않아도 돼요. 처음에는 가장 자주 반복하는 명령어 하나를 스크립트로 옮기는 것부터 시작해 보세요. 그것이 쌓여 거대한 자동화 파이프라인이 된답니다.

오늘 바로 할 일: 프로젝트 루트에 .dockerignore 파일이 있는지 확인하고 불필요한 폴더를 추가해 보세요.
이번 주 목표: 자주 쓰는 빌드 명령어를 하나의 .sh 파일로 만들어 보세요.
실행 직전 준비: 현재 배포 프로세스에서 가장 자주 발생하는 에러가 무엇인지 리스트를 만들어 보세요.

더 깊이 있는 컨테이너 운영 기술이 궁금하시다면, 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드를 먼저 읽어보시는 것을 추천드려요.