[IT-방법] 컴포즈 build 옵션 자동화와 CI/CD 연동 – 배포 과정을 손에서 놓는 기술

반복되는 배포 명령어가 주는 피로감에서 벗어나기

월요일 아침, 코드를 수정하고 서버에 반영하기 위해 터미널을 켭니다. 익숙한 손놀림으로 docker-compose up –build를 입력하죠. 하지만 이번에는 결과가 조금 다릅니다. 갑자기 빌드 컨텍스트 오류가 뜨거나, 이전의 잘못된 캐시가 남아 있어 엉뚱한 코드가 실행되기도 해요. 이런 상황이 반복되면 개발자의 집중력은 흐트러지고, 결국 배포 과정 자체가 두려운 숙제처럼 느껴지기 시작합니다.

많은 개발자가 배포를 단순히 명령어를 치는 행위라고 생각해요. 하지만 규모가 커질수록 무엇을 빌드할지, 어떤 인자를 넘길지, 빌드된 이미지를 어떻게 관리할지를 결정하는 빌드 옵션 관리가 업무의 핵심이 됩니다. 수동으로 진행하는 배포는 실수가 개입할 틈이 너무 많고, 사람이 직접 개입하는 순간 자동화의 가치는 사라져 버려요.

지금 이 글을 읽고 있는 분들도 비슷한 경험이 있을 거예요. 로컬 환경에서는 완벽하게 돌아가던 컨테이너가 서버에만 올라가면 환경 변수 문제로 멈춰버리거나, 빌드 속도가 너무 느려 답답했던 적 말이죠. 이제는 단순히 명령어를 실행하는 수준을 넘어, 컴포즈 build 옵션 자동화를 통해 배포 과정을 시스템의 영역으로 넘겨야 합니다.

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

• 매번 수동으로 설정하던 빌드 컨텍스트를 어떻게 깔끔하게 정리할까요?
• 환경별로 다른 빌드 인자를 어떻게 자동으로 주입할 수 있을까요?
• CI/CD 파이프라인에 도커 컴포즈 빌드를 어떻게 자연스럽게 녹여낼까요?
• 배포가 실패했을 때 어떻게 즉시 안전한 상태로 되돌릴까요?

단순히 이론만 늘어놓지 않을게요. 실제 현업에서 바로 적용할 수 있는 스크립트 구조와 설계 원칙을 중심으로 실질적인 해답을 찾아가 볼게요.

자동화 설계를 위한 사전 준비와 체크리스트

본격적으로 자동화 스크립트를 짜기 전에, 우리가 다루는 도구들이 무엇을 할 수 있는지 명확히 이해해야 해요. 무턱대고 파이프라인부터 만들다가는 빌드 속도 저하나 보안 사고라는 부메랑을 맞을 수 있거든요. 가장 먼저 도커 컴포즈의 빌드 구조를 다시 점검하는 작업이 필요합니다.

빌드 자동화를 위해서는 단순히 명령어 하나를 외우는 것이 아니라, 빌드 컨텍스트(Build Context)의 범위를 결정하는 능력이 중요해요. 빌드 컨텍스트란 도커 데몬이 빌드 과정에서 접근할 수 있는 파일들의 범위입니다. 이 범위가 너무 넓으면 불필요한 파일까지 모두 전송하느라 빌드 시간이 기하급수적으로 늘어나고, 너무 좁으면 필요한 설정 파일을 찾지 못해 오류가 발생하죠.

자동화 방식을 선택할 때 참고할 수 있는 비교 기준을 정리해 드릴게요. 현재 여러분의 팀 규모와 서비스 운영 환경에 따라 적절한 모델을 선택해 보세요.

위 표를 보면 알 수 있듯이, 서비스가 안정적인 운영 단계에 들어섰다면 이미지 레지스트리를 활용한 CI/CD 방식으로 넘어가는 것이 가장 권장되는 경로예요. 하지만 초기 단계이거나 소규모 프로젝트라면 CI/CD 파이프라인 내에서 직접 컴포즈 build 옵션을 제어하는 방식만으로도 충분한 효과를 볼 수 있습니다.

준비물은 명확해요. 도커와 도커 컴포즈 설치는 기본이고, 환경 변수를 관리할 .env 파일과 빌드 범위를 제한할 .dockerignore 파일이 반드시 준비되어 있어야 합니다. 이 두 가지가 준비되지 않은 상태에서의 자동화는 오히려 오류를 양산하는 지름길이 될 뿐이에요.

실전! 컴포즈 빌드 자동화 5단계 프로세스

이제 본격적으로 배포를 자동화하기 위한 핵심 단계들을 하나씩 밟아볼게요. 이 과정은 단순히 스크립트를 만드는 것이 아니라, 컨테이너가 생성되어 서버에 안착하기까지의 흐름을 설계하는 과정입니다.

STEP 1. 빌드 컨텍스트 최적화와 .dockerignore 설정

가장 먼저 해야 할 일은 도커가 빌드할 때 가져가는 파일들의 범위를 정하는 거예요. 많은 개발자가 실수하는 부분 중 하나가 프로젝트 루트 폴더 전체를 빌드 컨텍스트로 잡는 것입니다. 이렇게 되면 node_modules나 venv, 혹은 거대한 git 히스토리 파일까지 모두 도커 데몬으로 전송돼요. 이는 빌드 시작 전 ‘Sending build context to Docker daemon’ 단계에서 시간을 엄청나게 잡아먹는 주범이 됩니다.

이를 해결하려면 프로젝트 루트에 반드시 .dockerignore 파일을 만드세요. 여기에 제외할 목록을 명확히 적어줘야 합니다. 예를 들어 다음과 같은 구조를 권장해요.

• .git: 버전 관리 데이터는 빌드에 필요 없어요.
• node_modules/ 또는 venv/: 이미 설치된 라이브러리는 빌드 과정에서 새로 설치하도록 설계하는 것이 일관성에 좋습니다.
• * (전체 제외 후 필요한 것만 허용): 가장 안전한 방법이에요. 모든 파일을 무시하고, src/나 package.json 같은 핵심 파일만 화이트리스트로 등록하는 방식이죠.

이렇게 컨텍스트를 최적화하면 빌드 시작 속도가 눈에 띄게 빨라질 뿐만 아니라, 이미지 용량 자체도 가벼워져서 배포 효율이 극대화됩니다.

STEP 2. 빌드 인자(Args)와 환경 변수의 전략적 분리

자동화의 핵심은 build 옵션을 통해 상황에 맞는 값을 주입하는 거예요. 예를 들어 개발 환경에서는 디버그 모드를 켜고, 운영 환경에서는 보안 설정을 강화해야 하죠. 이때 도커 컴포즈의 build: args 옵션을 활용하면 됩니다.

여기서 주의할 점은 build args와 environment의 차이를 명확히 아는 거예요. args는 이미지를 만드는 시점(Build-time)에만 유효하고, environment는 컨테이너가 실행되는 시점(Run-time)에 유효합니다. API 키나 데이터베이스 비밀번호 같은 민감한 정보는 반드시 실행 시점에 주입되는 environment를 사용해야 보안 사고를 막을 수 있어요.

자동화 스크립트에서는 다음과 같이 .env 파일을 활용하는 패턴이 가장 효율적이에요.

STEP 3. CI/CD 파이프라인과 컴포즈 빌드 통합

이제 개별적인 설정들을 하나로 묶어 자동화 흐름을 만들 차례입니다. GitHub Actions를 기준으로 본다면, 전체 흐름은 다음과 같이 설계해야 해요.

1. 코드 푸시: 개발자가 코드를 메인 브랜치에 반영합니다.
2. 테스트 단계: 유닛 테스트를 실행하여 코드가 정상인지 확인합니다.
3. 빌드 및 푸시: CI 서버에서 docker-compose build 명령을 실행하고, 생성된 이미지를 레지스트리에 업로드합니다.
4. 서버 배포: SSH 등을 통해 운영 서버에 접속하여 docker-compose pull과 docker-compose up -d를 실행합니다.

이 과정에서 가장 중요한 기술적 포인트는 이미지 태깅(Tagging) 전략이에요. 항상 latest 태그만 사용하면 안 됩니다. 어떤 버전이 배포되었는지 추적하기 어렵고, 문제가 생겼을 때 이전 버전으로 되돌리기도 매우 힘들거든요. 대신 v1.0.1이나 ${GITHUB_SHA}(커밋 해시)를 태그로 사용하는 것이 가장 바람직합니다.

STEP 4. 배포 검증을 위한 헬스체크 자동화

빌드가 성공했다고 해서 배포가 완료된 것은 아니에요. 컨테이너가 뜨긴 했지만, 내부 앱이 에러를 내뿜으며 무한 재시작 중일 수도 있으니까요. 이를 방지하기 위해 Healthcheck 단계를 반드시 추가해야 합니다.

도커 컴포즈 파일에 healthcheck 옵션을 넣으면, 컨테이너가 단순히 ‘Running’ 상태인 것을 넘어 실제로 요청을 받을 준비가 되었는지 확인할 수 있어요. 예를 들어, 웹 서버라면 특정 엔드포인트인 /health에 주기적으로 요청을 보내 응답이 200 OK인지 체크하도록 설정하는 것이죠.

CI/CD 스크립트 마지막 단계에 간단한 Smoke Test를 넣는 것도 좋은 방법이에요. 배포 직후 스크립트가 서버의 API에 짧게 요청을 보내보고, 응답이 정상적이지 않으면 즉시 경고를 보내거나 롤백을 실행하도록 설계하면 운영 안정성이 비약적으로 상승합니다.

STEP 5. 장애 대응을 위한 자동 롤백 전략 구축

모든 자동화의 완성은 실패했을 때의 대응에 있습니다. 아무리 완벽한 파이프라인이라도 예상치 못한 버그는 발생할 수 있어요. 이때 수동으로 코드를 고치고 다시 빌드하는 것은 너무 느립니다.

가장 권장되는 전략은 앞서 언급한 ‘이미지 태깅’을 기반으로 한 롤백입니다. 만약 새로운 버전인 v2.0.0이 배포된 후 헬스체크에 실패한다면, 자동으로 이전 버전인 v1.9.9 이미지를 불러와 다시 docker-compose up -d를 실행하는 명령어를 파이프라인에 포함시키세요. 이것이 바로 ‘배포를 손에서 놓는’ 진짜 기술입니다.

이 5단계 프로세스를 하나씩 구축해 나가면, 여러분은 더 이상 배포할 때마다 긴장하며 터미널을 지켜보고 있지 않아도 될 거예요. 시스템이 대신 검증하고, 문제가 생기면 스스로 되돌리는 환경을 만드는 것, 그것이 바로 데브옵스의 핵심입니다.

자주 하는 실수와 해결법

자동화 과정에서 마주칠 수 있는 흔한 문제들을 정리했습니다. 비슷한 상황을 겪고 있다면 아래 해결책을 확인해 보세요.

• ❌ 빌드 속도가 너무 느려요
  → 왜 발생하는가: 빌드 컨텍스트에 불필요한 파일(예: .git, node_modules)이 너무 많이 포함되어 있습니다.
  → ✅ 해결법: .dockerignore 파일을 사용하여 전송할 파일의 범위를 최소화하세요.
• ❌ 로컬에서는 되는데 서버에서는 안 돼요
  → 왜 발생하는가: 환경 변수가 누락되었거나 빌드 시 사용한 인자(Args)가 서버 환경과 맞지 않기 때문입니다.
  → ✅ 해결법: .env 파일을 사용하여 환경별 설정을 명확히 분리하고, 빌드 인자와 실행 인자를 구분해서 관리하세요.
• ❌ 이미지가 계속 예전 버전으로 돌아가요
  → 왜 발생하는가: 태그를 latest로 고정해서 사용하고 있어, 새 이미지를 내려받아도 기존 이미지를 재사용하기 때문입니다.
  → ✅ 해결법: 커밋 해시나 버전 번호를 사용하여 고유한 태그를 부여하고, docker-compose pull을 명시적으로 호출하세요.
• ❌ 빌드 후에 서버 메모리가 부족해요
  → 왜 발생하는가: 빌드 과정에서 발생하는 임시 파일이나 캐시가 제대로 정리되지 않았기 때문입니다.
  → ✅ 해결법: 빌드 파이프라인 마지막 단계에 docker system prune -f 명령을 추가하여 사용하지 않는 이미지와 캐시를 주기적으로 정리하세요.
• ❌ 자동 배포 중에 서비스가 끊겨요
  → 왜 발생하는가: 기존 컨테이너를 중단한 뒤 새 컨테이너를 띄우는 사이에 간극이 발생하기 때문입니다.
  → ✅ 해결법: Blue-Green 배포 방식을 도입하거나, 도커 컴포즈의 업데이트 옵션을 활용해 교체 시간을 최소화하세요.

자주 묻는 질문

Q. 컴포즈 build 옵션 자동화가 왜 꼭 필요한가요?

사람이 직접 명령어를 입력하면 오타가 발생하거나 환경 변수를 잘못 넣는 실수가 반드시 생깁니다. 자동화는 이러한 인적 오류를 차단하고, 언제 어디서든 동일한 결과물을 만들어내는 ‘재현성’을 보장하기 때문에 필수적입니다.

Q. 빌드 컨텍스트를 넓게 잡으면 어떤 문제가 생기나요?

도커는 빌드를 시작하기 전에 컨텍스트에 포함된 모든 파일을 도커 데몬으로 복사합니다. 컨텍스트가 크면 네트워크나 디스크 I/O 부하가 커져서 빌드 시작 자체가 몇 분씩 걸릴 수 있고, 이미지 크기도 불필요하게 커집니다.

Q. CI/CD에서 build 옵션을 어떻게 제어하나요?
파이프라인 도구(GitHub Actions, Jenkins 등)의 설정 파일에서 도커 명령어를 실행할 때, 환경 변수를 주입하거나 --build-arg 옵션을 통해 원하는 값을 전달할 수 있습니다.

Q. 롤백은 어떻게 자동화하나요?
가장 쉬운 방법은 이전 버전의 이미지 태그를 기억해 두었다가, 헬스체크 실패 시 해당 태그로 다시 docker-compose up을 실행하는 스크립트를 파이프라인에 짜 넣는 것입니다.

Q. 컨테이너 운영 시 가장 주의할 점은 무엇인가요?
이미지의 불변성(Immutability)을 유지하는 것입니다. 한 번 빌드된 이미지는 그 내용이 절대 변하지 않아야 하며, 환경에 따른 차이는 이미지가 아닌 실행 시점의 설정값으로만 해결해야 합니다.

배포 자동화로 얻는 여유와 다음 단계

지금까지 컴포즈 build 옵션 자동화의 핵심부터 실무 적용 방법까지 살펴보았습니다. 처음에는 스크립트를 짜고 파이프라인을 구성하는 과정이 번거롭게 느껴질 수 있어요. 하지만 이 초기 투자 비용은 배포 때마다 겪는 스트레스와 장애 대응 비용에 비하면 아주 작은 수준입니다.

자동화가 구축되면 여러분은 더 이상 ‘배포가 성공할까?’라는 불안감에 떨지 않아도 됩니다. 시스템이 대신 검증하고, 문제가 생기면 스스로 복구하는 구조를 갖추는 순간, 개발자는 비로소 코드의 품질과 비즈니스 로직에만 집중할 수 있는 진정한 자유를 얻게 되거든요.

자, 이제 이론은 충분합니다. 실행이 답이에요. 거창한 파이프라인부터 만들려고 하지 마세요. 가장 자주 반복하는 명령 하나부터 스크립트로 옮겨 보세요. 작은 자동화가 모여 결국 여러분의 퇴근 시간을 앞당겨 줄 것입니다.

🚀 다음 단계로 나아가기

• 오늘 할 일: 현재 프로젝트의 .dockerignore 파일을 점검하고 불필요한 파일 제거하기
• 이번 주 할 일: 도커 컴포즈에 healthcheck 옵션을 추가하여 서비스 안정성 높이기
• 실행 직전 할 일: GitHub Actions를 활용해 간단한 빌드-푸시 파이프라인 만들어보기

관련해서 더 깊은 내용이 궁금하다면, 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드 글을 먼저 읽어보시는 것을 추천드려요. 기본기가 탄탄해야 자동화도 흔들리지 않습니다.