[IT-방법] 컴포즈 build 옵션 자동화와 CI/CD 연동 – 반복적인 배포 작업을 없애는 효율적인 설계

매번 반복되는 빌드 명령어가 당신의 시간을 뺏고 있어요

새로운 코드를 반영하려고 터미널을 열고 docker-compose build 명령어를 입력하는 순간을 떠올려 보세요. 빌드가 시작되고, 수많은 로그가 올라가는 것을 지켜보며 커피 한 잔을 마시죠. 그런데 갑자기 빌드가 실패했다는 메시지가 뜨면 기분이 어떠신가요? 오타 하나 때문인지, 아니면 빌드 컨텍스트 설정이 잘못된 것인지 확인하느라 또 30분을 허비하게 돼요.

이런 상황이 매일 반복된다면 그것은 더 이상 단순한 작업이 아니라 비효율적인 노동이에요. 숙련된 개발자일수록 명령어를 직접 입력하기보다, 시스템이 스스로 판단하고 움직이게 만드는 구조를 설계하는 데 집중해요. 컴포즈 build 옵션 자동화는 바로 이 지점에서 시작돼요. 단순히 명령어를 대신 쳐주는 것을 넘어, 빌드 환경 자체를 표준화하고 실수를 원천 차단하는 과정이거든요.

지금 이 글을 읽고 계신 분들은 아마 배포 과정에서 발생하는 사소하지만 치명적인 실수들 때문에 골머리를 앓고 계실 거예요. 컨테이너가 구동되지 않거나, 이전 버전의 이미지가 그대로 남아 있거나, 빌드 속도가 너무 느려 답답함을 느끼는 분들이 대상이에요. 이 글을 끝까지 읽고 나면 수동 배포의 굴레에서 벗어나 자동화된 파이프라인을 구축하는 구체적인 로드맵을 얻게 될 거예요.

이번 글에서는 다음과 같은 내용을 구체적으로 다뤄요.

• 빌드 컨텍스트를 최적화하여 속도를 높이는 방법
• 환경 변수를 활용한 동적인 build 옵션 제어 기술
• CI/CD 파이프라인에 컴포즈를 녹여내는 설계 원칙
• 배포 실패 시 즉시 복구할 수 있는 롤백 전략

자동화를 시작하기 전 반드시 점검해야 할 핵심 요소

무턱대고 스크립트부터 짜는 것은 위험해요. 기초 공사가 부실하면 자동화 도구가 오히려 장애를 일으키는 주범이 될 수 있거든요. 가장 먼저 살펴봐야 할 것은 빌드 컨텍스트(Build Context)의 범위예요. 도커가 빌드를 수행할 때 현재 디렉토리의 모든 파일을 전송한다면, 불필요한 데이터 때문에 빌드 속도가 기하급수적으로 느려져요.

또한, 컴포즈 파일 내에서 build 옵션을 어떻게 정의했는지도 점검해야 해요. 단순히 경로만 지정했는지, 아니면 다양한 환경에 대응할 수 있도록 인자(args)를 설계했는지에 따라 자동화의 수준이 완전히 달라져요. 자동화의 목적은 ‘사람의 개입 없이도 일관된 결과물을 만드는 것’임을 잊지 마세요.

자동화 방식을 결정하기 위해 아래 표를 참고해서 현재 운영 환경에 맞는 기준을 세워보세요.

어떤 방식을 선택하든 핵심은 재현 가능성이에요. 동일한 코드를 넣었을 때, 언제 어디서 빌드하더라도 똑같은 이미지와 컨테이너가 생성되어야 해요. 이를 위해 환경 변수 관리와 버전 관리가 선행되어야 함을 명심하세요.

실전! 컴포즈 빌드 자동화 구축 5단계

이제 이론을 넘어 실제로 동작하는 시스템을 만들어볼 시간이에요. 단계별로 차근차근 따라오시면 복잡해 보이던 빌드 과정이 하나의 흐름으로 연결되는 것을 경험할 수 있어요.

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

자동화의 첫 단추는 빌드 효율성을 극대화하는 것이에요. 많은 개발자가 실수하는 부분 중 하나가 빌드 컨텍스트에 너무 많은 파일을 포함하는 것이에요. build context가 커지면 도커 데몬으로 파일을 전송하는 시간만으로도 엄청난 지연이 발생해요.

먼저 프로젝트 루트 디렉토리에 .dockerignore 파일을 만드세요. 여기에 반드시 제외해야 할 목록을 적어 넣어야 해요. 예를 들어 node_modules, .git, venv, 그리고 각종 로그 파일들을 포함하세요. 이렇게 하면 빌드 속도가 이전보다 2~3배 이상 빨라지는 것을 체감할 수 있어요. 또한, 컨테이너 내부의 이미지 크기를 줄여서 배포 시 전송 시간을 단축하는 효과도 얻을 수 있어요.

STEP 2. 환경 변수를 이용한 동적 build args 설계

운영(Production) 환경과 테스트(Staging) 환경은 설정값이 다를 수밖에 없어요. 이때 매번 Dockerfile을 수정하는 것은 최악의 방법이에요. 대신 docker-compose.yml의 build: args 기능을 활용하세요.

예를 들어, 다음과 같이 설정할 수 있어요.

이 방식은 단 하나의 Dockerfile로 여러 환경을 모두 커버할 수 있게 해줘요. 코드의 중복을 없애고 관리 포인트를 하나로 통합하는 핵심 기술이에요.

STEP 3. 쉘 스크립트를 이용한 빌드 자동화 명령 작성

이제 명령어들을 하나로 묶을 차례예요. 매번 긴 옵션을 입력하는 대신, 짧은 스크립트로 처리하세요. 단순한 build.sh 파일을 만들어 관리하면 매우 편리해요.

스크립트에는 다음과 같은 로직이 포함되어야 해요. 첫째, 현재 환경 변수가 설정되어 있는지 확인해요. 둘째, 기존의 오래된 이미지를 정리할지 선택해요. 셋째, docker-compose build --pull 명령어를 통해 최신 베이스 이미지를 가져오며 빌드해요. 마지막으로 빌드가 성공했는지 체크하는 로직을 넣으세요. 쉘 스크립트의 종료 코드($?)를 확인하면 빌드 성공 여부를 판단할 수 있어요. 이렇게 하면 사람이 명령어를 치다가 실수할 확률을 획기적으로 줄일 수 있어요.

STEP 4. CI/CD 파이프라인(GitHub Actions) 통합

진정한 자동화의 완성은 코드 푸시(Push)만으로 배포가 이루어지는 CI/CD 연동이에요. GitHub Actions를 예로 들어볼게요. 코드가 main 브랜치에 머지되면 자동으로 워크플로우가 실행되도록 설계하세요.

워크플로우의 흐름은 다음과 같아요. 1) 코드를 체크아웃하고, 2) 필요한 환경 변수를 세팅하며, 3) Docker 빌드를 수행하고, 4) 생성된 이미지를 컨테이너 레지스트리(Docker Hub, ECR 등)에 푸시해요. 5) 마지막으로 운영 서버에 접속하여 docker-compose pull과 docker-compose up -d를 실행하도록 명령을 내려요. 이 과정이 한 번 세팅되면, 개발자는 오직 코드 작성에만 집중할 수 있어요.

STEP 5. 배포 검증 및 자동 롤백 로직 구현

배포가 완료되었다고 끝이 아니에요. 컨테이너가 떴더라도 실제 서비스가 정상적으로 작동하는지는 별개의 문제니까요. 빌드 자동화 파이프라인 마지막 단계에 헬스 체크(Health Check) 단계를 반드시 추가하세요.

도커 컴포즈 파일에 healthcheck 옵션을 넣어 컨테이너의 상태를 정의하세요. 만약 컨테이너가 unhealthy 상태로 변하면, 스크립트가 이를 감지하여 자동으로 이전 버전의 이미지로 되돌리는(Rollback) 작업을 수행해야 해요. 이를 위해 이전 이미지 태그를 저장해두는 간단한 로직을 스크립트에 포함시키는 것이 좋아요. 실패를 두려워하지 않는 시스템을 만드는 것이 진정한 데브옵스의 정신이에요.

자주 하는 실수와 해결법 및 자주 묻는 질문

자동화 시스템을 구축하다 보면 예상치 못한 곳에서 에러가 발생하곤 해요. 시행착오를 줄이기 위해 가장 흔하게 겪는 문제들을 정리해 두었으니 참고하세요.

• ❌ 실수: .dockerignore 파일을 만들지 않아 빌드 속도가 너무 느려요.
  왜 발생하는가: 불필요한 로컬 라이브러리와 데이터가 모두 빌드 컨텍스트로 전송되기 때문이에요.
  ✅ 해결법: 프로젝트 루트에 .dockerignore를 만들고 제외할 목록을 명확히 기재하세요.
• ❌ 실수: 환경 변수가 빌드 시점에 반영되지 않아요.
  왜 발생하는가: Dockerfile 내부에서 ARG를 정의하지 않았거나, compose 파일에서 args로 전달하지 않았기 때문이에요.
  ✅ 해결법: Dockerfile 상단에 ARG를 선언하고, compose 파일의 build 섹션에 args 항목을 추가하세요.
• ❌ 실수: CI/CD 파이프라인에서 빌드된 이미지를 찾을 수 없다고 나와요.
  왜 발생하는가: 이미지를 푸시(Push)하지 않았거나, 서버에서 풀(Pull)하기 전에 태그가 변경되었기 때문이에요.
  ✅ 해결법: 이미지 태그를 고유한 값(예: Git Commit Hash)으로 지정하여 관리하세요.
• ❌ 실수: 빌드가 성공했는데 이전 버전 코드가 실행돼요.
  왜 발생하는가: 도커의 레이어 캐시가 이전 빌드 결과물을 그대로 사용했기 때문이에요.
  ✅ 해결법: 빌드 명령 시 –no-cache 옵션을 사용하거나, 캐시 무효화를 위해 인자(args)를 변경하세요.
• ❌ 실수: 서버 용량이 갑자기 부족해져요.
  왜 발생하는가: 오래된 빌드 이미지와 중지된 컨테이너들이 쌓여 있기 때문이에요.
  ✅ 해결법: 주기적으로 docker system prune 명령어를 실행하는 자동화 스케줄러를 만드세요.

자주 묻는 질문

Q. 로컬에서 빌드하는 것과 CI 서버에서 빌드하는 것의 차이가 큰가요?

네, 꽤 커요. 로컬은 환경이 파편화되어 있어 “내 컴퓨터에서는 되는데 서버에서는 안 돼요”라는 상황이 자주 발생해요. 그래서 CI 서버처럼 깨끗하고 표준화된 환경에서 빌드하는 것이 훨씬 안전해요.

Q. 컴포즈 build 옵션을 자동화할 때 보안은 어떻게 관리하나요?
가장 중요한 질문이에요. API 키나 데이터베이스 비밀번호 같은 민감한 정보는 절대 Dockerfile이나 compose 파일에 직접 적지 마세요. 대신 환경 변수나 Secret 관리 도구를 사용하고, 빌드 시점에만 주입되도록 설계해야 해요.

Q. 빌드 속도를 더 올릴 수 있는 방법이 있을까요?
멀티 스테이지 빌드(Multi-stage build)를 사용해 보세요. 빌드 단계와 실행 단계를 분리하면, 최종 이미지에 필요한 도구들만 포함되어 용량이 획기적으로 줄어들고 속도도 빨라져요.

Q. 롤백을 할 때 이미지를 삭제해야 하나요?
아니요, 삭제하기보다는 태그 관리가 핵심이에요. 이전 버전의 이미지 태그를 유지하고 있다가, 문제가 생기면 해당 태그로 다시 pull 하여 실행하는 방식이 가장 빠르고 안전해요.

이제 반복 작업에서 벗어나 가치를 만드는 일에 집중하세요

지금까지 컴포즈 build 옵션 자동화와 이를 CI/CD 파이프라인에 녹여내는 전 과정을 살펴보았어요. 처음에는 설정할 것이 많아 번거롭게 느껴질 수 있지만, 한 번 제대로 구축해 놓으면 여러분의 퇴근 시간이 달라질 거예요. 자동화는 단순히 편해지기 위한 도구가 아니라, 시스템의 안정성을 확보하고 인간의 실수를 방지하는 가장 강력한 방어선이에요.

오늘 배운 내용을 바탕으로 바로 시작해 볼 수 있는 단계별 실천 가이드를 제안할게요.

• 오늘 할 일: 현재 프로젝트에 .dockerignore 파일이 있는지 확인하고 불필요한 파일을 정리해 보세요.
• 이번 주 할 일: 자주 쓰는 빌드 명령어를 담은 간단한 .sh 스크립트를 작성해 보세요.
• 실행 직전 할 일: GitHub Actions나 GitLab CI를 통해 빌드 자동화 흐름을 한 번만 돌려보세요.

가장 자주 반복하는 명령 하나부터 스크립트로 옮겨 보세요. 작은 자동화가 모여 큰 시스템의 안정성을 만듭니다. 지금 바로 터미널을 열고 첫 번째 스크립트를 작성해 보시길 권장해요.

관련하여 더 깊은 내용이 궁금하다면 아래 글을 참고해 보세요.
도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드