[IT-방법] 컴포즈 build 옵션 자동화 가이드 – CI/CD 연동으로 배포 스트레스에서 벗어나는 법

반복되는 배포 명령, 언제까지 직접 입력하실 건가요?

퇴근을 불과 30분 앞둔 시점, 갑자기 발견된 코드 버그 때문에 다시 터미널을 켜고 계신가요? docker-compose build를 입력하고, 빌드 인자가 틀려 에러를 마주하며, 컨텍스트 경로가 잘못되었다는 메시지에 다시 명령어를 수정하는 과정은 정말 지치기 마련이에요. 단순한 명령 한 줄이지만, 매일 수십 번씩 반복하다 보면 어느덧 손가락은 익숙해져도 마음은 불안해지기 시작하죠. 혹시 내가 이번에 빌드 인자를 빠뜨리지는 않았는지, 엉뚱한 경로를 빌드 컨텍스트로 잡지는 않았는지 걱정하며 배포 버튼을 누르고 계시지는 않나요?

이런 수동 배포의 한계는 단순히 귀찮음을 넘어 실무에서 치명적인 사고로 이어질 수 있어요. 사람이 하는 일에는 반드시 실수가 따르기 때문이죠. 특히 컨테이너 환경이 복잡해질수록 컴포즈 build 옵션 하나를 잘못 설정하는 것만으로도 운영 서버에 엉뚱한 이미지가 올라가거나, 보안상 민감한 정보가 빌드 과정에 포함되는 불상사가 생길 수 있어요. 이제는 명령어를 외우고 타이핑하는 단계에서 벗어나, 시스템이 알아서 정확하게 빌드하고 배포하도록 만드는 컴포즈 build 옵션 자동화가 필요한 시점이에요.

지금 이 글을 읽고 계신 분들은 아마도 매일 반복되는 배포 작업에 피로감을 느끼거나, 배포 과정의 안정성을 높이고 싶은 개발자 또는 서버 운영자일 거예요. 이 글을 끝까지 따라오시면 더 이상 터미널 앞에서 오타를 걱정하며 떨지 않아도 돼요. 자동화된 파이프라인을 통해 배포를 ‘손에서 놓는’ 경험을 하게 될 거예요.

오늘 함께 살펴볼 내용은 다음과 같아요.

• 컴포즈 build 옵션의 핵심 구성 요소와 올바른 설정 방법
• 빌드 속도와 효율을 극대화하는 컨텍스트 관리 전략
• 쉘 스크립트와 CI/CD를 결합한 단계별 자동화 설계
• 배포 실패를 방지하기 위한 검증 및 롤백 프로세스

자동화 시작 전, 반드시 점검해야 할 핵심 개념

본격적으로 스크립트를 짜거나 파이프라인을 구축하기 전에, 우리가 제어하고자 하는 대상이 무엇인지 정확히 알아야 해요. 무작정 자동화 도구를 도입한다고 해서 모든 문제가 해결되지는 않거든요. 우선 도커 컴포즈 환경에서 빌드가 일어나는 메커니즘을 완벽히 이해하는 것이 첫걸음이에요.

빌드 컨텍스트와 옵션의 상관관계

가장 먼저 이해해야 할 것은 ‘빌드 컨텍스트(Build Context)’예요. 도커가 이미지를 만들 때 어떤 파일들을 가져가서 작업할지 결정하는 범위라고 생각하면 쉬워요. 만약 이 범위를 너무 넓게 잡으면 불필요한 파일까지 모두 도커 데몬으로 전송하게 되어 빌드 속도가 급격히 느려져요. 반대로 너무 좁게 잡으면 빌드에 필요한 설정 파일이나 소스 코드를 찾지 못해 에러가 발생하죠. 따라서 build 옵션의 context 경로를 정확히 지정하는 것이 자동화의 기초 중의 기초예요.

또한, 빌드 시점에 주입하는 build args 역시 매우 중요해요. 운영 환경과 개발 환경에서 서로 다른 API 키나 데이터베이스 접속 정보를 사용해야 할 때, 이 인자들을 어떻게 자동화된 방식으로 넘겨줄지 결정해야 하거든요. 이 과정이 정교하지 않으면 자동화는 오히려 보안 구멍을 만드는 도구가 될 수도 있어요.

운영 환경별 자동화 접근 방식 비교

현재 여러분의 팀이나 프로젝트 규모에 따라 가장 적합한 자동화 방식은 달라질 수 있어요. 아래 표를 통해 어떤 방식을 선택해야 할지 판단 기준을 확인해 보세요.

결국 자동화의 목적은 ‘재현 가능성’을 확보하는 것에 있어요. 누가, 언제, 어디서 실행하더라도 똑같은 결과물이 나올 수 있도록 환경을 준비하는 것이 우선이에요. 이제 준비가 되었다면, 구체적으로 어떻게 빌드 옵션을 설계하고 자동화할 수 있는지 단계별로 알아볼까요?

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

이제 이론을 넘어 실제 코드를 만질 시간이에요. 단순히 명령어를 묶는 것을 넘어, 효율적이고 안전한 컴포즈 build 옵션 자동화를 구축하는 과정을 5단계로 나누어 설명해 드릴게요.

STEP 1. docker-compose.yml의 build 옵션 정교화하기

자동화의 첫 단추는 컴포즈 파일 자체를 기계가 읽기 좋고 명확하게 만드는 거예요. 단순히 build: .라고 적는 것은 지양해야 해요. 명확한 경로와 인자를 명시해야 나중에 자동화 스크립트가 이 값을 제어하기 쉬워지거든요.

예를 들어, 다음과 같이 작성해 보세요.

services:
  web-app:
    build:
      context: . 
      dockerfile: ./deploy/Dockerfile.prod
      args:
        - NODE_ENV=production
        - API_VERSION=v1.2.0

이렇게 작성하면 빌드할 때 사용하는 Dockerfile의 위치를 명확히 할 수 있고, 외부에서 주입할 인자들을 미리 정의해 둘 수 있어요. 이렇게 하면 자동화 도구가 환경 변수를 읽어와서 저 API_VERSION 부분만 쏙 갈아 끼우기가 훨씬 수월해져요.

STEP 2. .dockerignore를 통한 빌드 컨텍스트 최적화

자동화된 빌드에서 가장 많이 발생하는 병목 현상은 바로 ‘느린 빌드 속도’예요. 빌드할 때마다 node_modules나 대용량 로그 파일, 로컬 데이터베이스 파일이 도커 빌드 컨텍스트로 전송되고 있다면 어떨까요? 빌드가 끝날 때까지 커피 한 잔을 마시고 와도 모자랄 거예요.

.dockerignore 파일을 반드시 만드세요. 프로젝트 루트에 이 파일을 두고, 불필요한 파일들을 제외시켜야 해요.

• node_modules/: 종속성 라이브러리는 이미지 내부에서 다시 설치하는 게 훨씬 빨라요.
• .git/: 버전 관리 기록은 빌드 이미지에 필요하지 않아요.
• *.log: 실행 로그는 빌드 컨텍스트를 무겁게 만들 뿐이에요.
• dist/ 또는 build/: 이미 빌드된 결과물이 있으면 충돌을 일으킬 수 있어요.

이렇게 컨텍스트를 최적화하면 빌드 시작 전 파일을 전송하는 단계(Sending build context to Docker daemon)가 몇 초 내로 끝나게 되어 전체적인 자동화 사이클이 눈에 띄게 빨라져요.

STEP 3. 쉘 스크립트를 활용한 로컬 배포 자동화

CI/CD를 구축하기 전, 우선 로컬이나 개발 서버에서 사용할 수 있는 쉘 스크립트를 만들어 보세요. 스크립트는 명령어를 단순히 나열하는 것이 아니라, ‘실패했을 때의 행동’까지 포함해야 해요.

아래는 실무에서 바로 응용할 수 있는 자동화 스크립트 예시예요.

#!/bin/bash

# 1. 이전 빌드 잔해 정리
docker-compose down --remove-orphans

# 2. 빌드 시작 (에러 발생 시 중단) 
# --build 옵션을 사용하여 항상 새로 빌드하도록 강제해요
docker-compose build --no-cache || { echo "빌드 실패! 중단합니다."; exit 1; }

# 3. 서비스 실행
docker-compose up -d || { echo "컨테이너 실행 실패!"; exit 1; }

# 4. 상태 확인
docker-compose ps
echo "배포가 완료되었습니다!"

여기서 핵심은 || { exit 1; } 부분이에요. 중간 단계에서 에러가 났는데도 무시하고 다음 명령어로 넘어간다면, 잘못된 상태로 서비스가 구동되는 최악의 상황을 맞이하게 돼요. 스크립트는 항상 성공과 실패를 명확히 구분해야 해요.

STEP 4. GitHub Actions를 이용한 CI/CD 파이프라인 구축

이제 진정한 자동화인 CI/CD 단계로 넘어갑니다. 코드가 메인 브랜치에 푸시되면 자동으로 빌드되고 서버에 배포되는 구조를 만들어야 해요. GitHub Actions를 사용하면 매우 간단하게 구현할 수 있어요.

워크플로우 파일(.yml)의 구조는 대략 다음과 같이 설계하세요.

1. Checkout: 코드를 워크플로우 환경으로 가져옵니다.
2. Docker Login: 빌드된 이미지를 저장할 레지스트리(Docker Hub, ECR 등)에 로그인합니다.
3. Build & Push: 컴포즈 build 옵션을 활용해 이미지를 빌드하고 레지스트리에 업로드합니다.
4. Deploy: 운영 서버에 접속하여 docker-compose pull과 up -d를 실행합니다.

이때 secrets 기능을 활용해 서버 접속 정보나 API 키를 관리해야 한다는 점을 잊지 마세요. 코드가 노출되어도 실제 비밀번호는 안전하게 보호되어야 하니까요.

STEP 5. 환경 변수(Env) 기반의 멀티 스테이지 빌드 전략

마지막 단계는 빌드된 이미지의 크기를 줄이고 보안을 강화하는 거예요. 멀티 스테이지 빌드(Multi-stage Build)를 사용하면 빌드 도구(컴파일러 등)는 빌드 단계에서만 쓰고, 최종 실행 이미지에는 실행에 필요한 최소한의 파일만 남길 수 있어요.

컴포즈의 build args와 이 멀티 스테이지를 결합하면, 하나의 Dockerfile로 개발용, 테스트용, 운영용 이미지를 모두 만들어낼 수 있어요. 운영용 이미지는 용량이 작아서 배포 속도가 빠르고, 보안 공격 표면도 획기적으로 줄어들죠. 이것이 바로 진정한 의미의 고급 자동화 기술이에요.

자주 하는 실수와 해결법 및 FAQ

자동화를 구축하다 보면 예상치 못한 에러 때문에 막막할 때가 있죠. 실무에서 가장 자주 발생하는 문제들을 정리해 두었으니, 문제가 생기면 바로 확인해 보세요.

자주 하는 실수와 해결법

❌ 실수: 빌드 컨텍스트 경로 오류
왜 발생하는가: docker-compose.yml에 적힌 context 경로가 실제 폴더 구조와 다르거나 상대 경로 계산을 잘못했을 때 발생해요.
✅ 해결법: 항상 컴포즈 파일 위치를 기준으로 경로를 재점검하세요. 가급적이면 절대 경로보다는 프로젝트 루트를 기준으로 한 상대 경로를 사용하고, pwd 명령어로 현재 위치를 확인하는 습관을 들이세요.

❌ 실수: 빌드 인자(Args) 전달 실패
왜 발생하는가: 컴포즈 파일의 args에는 정의했지만, 정작 Dockerfile 내부에서 ARG 명령어로 받지 않았을 때 발생해요.
✅ 해결법: 컴포즈의 args 섹션과 Dockerfile의 ARG 선언이 1:1로 매칭되는지 반드시 확인하세요.

❌ 실수: 캐시(Cache)로 인한 구버전 이미지 빌드
왜 발생하는가: 코드는 바뀌었지만 도커가 이전 레이어의 캐시를 그대로 사용하여 변경 사항이 반영되지 않을 때가 있어요.
✅ 해결법: 자동화 스크립트에서 docker-compose build --no-cache 옵션을 사용하여 클린 빌드를 수행하거나, 특정 레이어만 깨뜨릴 수 있도록 환경 변수를 활용하세요.

❌ 실수: CI 환경에서의 권한 문제
왜 발생하는가: GitHub Actions 같은 CI 도구가 서버에 접속할 때 SSH 키 권한이 없거나, 도커 소켓(/var/run/docker.sock) 접근 권한이 없을 때 발생해요.
✅ 해결법: 서버의 docker 그룹에 실행 사용자를 추가하거나, SSH 키를 secrets에 안전하게 등록하여 인증 과정을 자동화하세요.

❌ 실수: .dockerignore 미사용으로 인한 빌드 지연
왜 발생하는가: 불필요한 데이터가 계속 전송되어 빌드 시간이 기하급수적으로 늘어나는 경우예요.
✅ 해결법: 프로젝트 루트에 .dockerignore를 즉시 생성하고, 불필요한 폴더를 모두 등록하세요.

자주 묻는 질문

Q. 컴포즈 빌드 자동화를 하면 보안상 위험하지 않나요?

전혀 그렇지 않아요. 오히려 사람이 직접 명령어를 입력할 때 발생하는 실수(예: 환경 변수를 터미널에 노출하는 행위)를 막아주죠. 대신 CI/CD 도구의 secrets 기능을 사용하여 비밀 정보를 철저히 관리하는 것이 핵심이에요.

Q. 빌드 속도를 줄이는 가장 효과적인 방법은 무엇인가요?

두 가지를 병행하세요. 첫째는 .dockerignore를 통해 컨텍스트 크기를 줄이는 것이고, 둘째는 Dockerfile 내에서 자주 바뀌지 않는 레이어(예: 라이브러리 설치 단계)를 상단에 배치하여 캐시 효율을 높이는 거예요.

Q. 쉘 스크립트와 CI/CD 중 무엇부터 시작해야 할까요?

먼저 쉘 스크립트로 배포 과정을 표준화하세요. 스크립트가 완벽하게 작동한다면, 그 스크립트를 CI/CD 도구가 대신 실행하게 만드는 것이 가장 부드러운 전환 방법이에요.

Q. 빌드 인자(Args)와 환경 변수(Env)의 차이가 무엇인가요?
args는 이미지를 만드는 ‘빌드 시점’에만 사용되는 값이고, environment는 컨테이너가 ‘실행되는 시점’에 사용되는 값이에요. 용도에 맞게 구분해서 써야 해요.

Q. 배포가 실패했을 때 자동으로 되돌리는(Rollback) 방법이 있나요?

스크립트 내에서 에러 발생 시 이전 태그의 이미지를 다시 docker-compose up -d 하도록 작성하거나, Kubernetes 같은 오케스트레이션 도구를 도입하면 더 강력한 자동 롤백이 가능해져요.

이제 당신의 배포는 시스템의 몫입니다

지금까지 컴포즈 build 옵션을 어떻게 자동화하고, 이를 통해 어떻게 안정적인 CI/CD 파이프라인을 구축할 수 있는지 깊이 있게 살펴보았어요. 처음에는 스크립트 한 줄, 설정 하나를 바꾸는 것이 번거롭게 느껴질 수 있지만, 한 번 구축해 놓은 자동화는 여러분의 퇴근 시간을 앞당겨주고 심리적인 안정감을 줄 거예요.

자동화는 한 번에 완성되는 것이 아니라, 운영하면서 계속해서 다듬어가는 과정이에요. 에러가 발생하면 그 에러를 해결하는 스크립트를 추가하고, 빌드가 느려지면 컨텍스트를 다시 점검하는 과정 자체가 여러분의 데브옵스 역량을 키워주는 소중한 자산이 됩니다.

실행을 망설이지 마세요. 거창한 시스템이 아니어도 좋아요. 가장 자주 반복하는 명령어 하나부터 스크립트로 옮겨 보세요. 그것이 자동화로 가는 가장 빠르고 확실한 길이니까요.

🚀 다음 단계로 나아가기

• 오늘 할 일: 현재 프로젝트의 .dockerignore 파일 상태 점검하기
• 이번 주 할 일: 배포 명령어를 담은 간단한 deploy.sh 스크립트 작성하기
• 실행 직전 할 일: GitHub Actions 워크플로우 기본 템플릿 찾아보기

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