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

반복되는 수동 배포의 늪에서 벗어나야 하는 이유

매일 퇴근 직전, 서버에 SSH로 접속해 docker-compose up --build 명령어를 입력하며 초조하게 로그를 지켜본 적이 있나요? 빌드가 성공하기를 기도하며 커피 한 잔을 마시지만, 예상치 못한 빌드 오류가 뜨는 순간 밀려오는 피로감은 이루 말할 수 없어요. 단순히 명령어를 입력하는 과정이 문제가 아니에요. 환경 변수가 바뀌었는지, 빌드 컨텍스트에 불필요한 파일이 포함되어 속도가 느려지지는 않았는지 일일이 확인해야 하는 그 과정 전체가 우리의 에너지를 갉아먹고 있어요.

특히 서비스 규모가 커지고 마이크로서비스 아키텍처(MSA)를 채택하게 되면, 관리해야 할 컨테이너 개수는 기하급수적으로 늘어나요. 이 모든 것을 사람이 일일이 명령어를 입력하며 관리하는 것은 사실상 불가능에 가까워요. 실수 한 번이 전체 서비스 장애로 이어질 수 있다는 압박감은 개발자의 생산성을 떨어뜨리는 주범이에요. 이제는 컴포즈 build 옵션 자동화를 통해 사람이 개입하는 영역을 최소화하고, 시스템이 스스로 빌드하고 배포하는 환경을 만들어야 해요.

자동화는 단순히 편해지기 위한 수단이 아니에요. 배포의 일관성을 유지하고, 인적 오류를 차단하며, 결과적으로 더 가치 있는 코드 작성에 집중할 수 있는 시간을 벌어다 주는 핵심 전략이에요. 오늘 이 글을 끝까지 읽으시면, 지긋지긋한 수동 빌드 작업에서 벗어나 안정적인 파이프라인을 구축하는 구체적인 방법을 얻어 가실 수 있어요.

이 글에서는 다음과 같은 내용을 핵심적으로 다뤄요.

• 수동 빌드에서 발생하는 치명적인 문제점과 자동화의 필요성
• 효율적인 빌드를 위한 컴포즈 build 옵션과 컨텍스트 최적화 방법
• 쉘 스크립트와 CI/CD 도구를 활용한 배포 자동화 파이프라인 설계
• 배포 실패 시 안전하게 이전 상태로 되돌리는 롤백 전략

자동화를 시작하기 전 반드시 챙겨야 할 기초 지식

무작정 스크립트를 짜거나 CI/CD 도구를 설치한다고 해서 자동화가 완성되는 것은 아니에요. 오히려 제대로 된 준비 없이 시작했다가는 빌드 속도가 더 느려지거나, 보안상 위험한 환경 변수가 코드에 노출되는 사고를 겪을 수 있어요. 본격적인 자동화 설계에 들어가기 전에, 우리가 제어해야 할 대상이 무엇인지 정확히 이해하는 과정이 필요해요.

가장 먼저 이해해야 할 개념은 빌드 컨텍스트(Build Context)예요. 도커는 빌드를 수행할 때 지정된 디렉토리의 모든 파일을 도커 데몬으로 전송해요. 만약 불필요한 로그 파일이나 대용량 데이터셋이 이 디렉토리에 포함되어 있다면, 빌드할 때마다 엄청난 양의 데이터를 전송하느라 시간이 허비돼요. 따라서 무엇을 포함하고 무엇을 제외할지 결정하는 dockerignore 설정은 자동화의 첫 단추라고 할 수 있어요.

또한, 컴포즈 파일 내에서 사용하는 build 옵션의 종류를 숙지해야 해요. 단순히 이미지를 만드는 것을 넘어, 빌드 시점에 동적으로 값을 주입하는 args와 실행 시점에 환경을 결정하는 environment의 차이를 명확히 구분해야 해요. 이를 혼동하면 빌드 환경과 실행 환경이 뒤섞여 “내 컴퓨터에서는 되는데 서버에서는 안 돼요”라는 고전적인 문제를 겪게 돼요.

자동화 수준을 결정할 때는 우리 팀의 규모와 서비스의 중요도를 고려해야 해요. 아래 표를 통해 현재 우리 팀에 가장 적합한 방식이 무엇인지 비교해 보세요.

처음부터 완벽한 CI/CD를 구축하려고 욕심부릴 필요는 없어요. 우선 반복되는 명령어를 스크립트로 묶는 것부터 시작해서, 점진적으로 자동화 범위를 넓혀가는 것이 가장 현실적이고 안전한 방법이에요.

컴포즈 빌드 자동화를 구현하는 5단계 프로세스

이제 본격적으로 실무에 바로 적용할 수 있는 자동화 설계 방법을 알아볼게요. 단순히 명령어를 나열하는 것이 아니라, 빌드 효율을 높이고 운영의 안정성을 확보하는 데 초점을 맞춰야 해요. 각 단계를 차근차근 따라오시면 여러분만의 배포 파이프라인을 가질 수 있어요.

STEP 1. 빌드 컨텍스트와 도커파일 최적화

자동화의 첫 번째 단계는 빌드 속도를 결정짓는 환경을 만드는 것이에요. 빌드 속도가 느리면 자동화 파이프라인 전체가 지체되어 개발 피드백 루프가 길어지거든요. 이를 위해 가장 먼저 dockerignore 파일을 작성해야 해요.

프로젝트 루트 디렉토리에 .dockerignore 파일을 만들고, 다음과 같은 항목들을 반드시 포함하세요. node_modules, .git, venv, dist, logs, *.log 같은 파일들은 빌드 컨텍스트에 포함될 필요가 전혀 없어요. 만약 이 파일들이 포함되면 도커 데몬으로 수백 메가바이트의 데이터를 전송하게 되어 빌드 시작 단계에서부터 엄청난 시간이 소요돼요. 또한, 빌드 단계에서 생성되는 임시 파일들도 모두 제외 목록에 넣어야 해요.

도커파일(Dockerfile) 작성 시에는 레이어 캐싱을 최대한 활용할 수 있도록 구조를 설계해야 해요. 자주 변하지 않는 패키지 설치 명령(예: npm install, pip install)을 소스 코드 복사 명령(COPY .)보다 앞 순서에 배치하세요. 이렇게 하면 소스 코드가 한 줄만 바뀌어도 모든 패키지를 다시 설치하는 비효율을 막을 수 있어요.

STEP 2. 컴포즈 build 옵션의 동적 제어

환경마다 다른 빌드 설정값을 일일이 수정하는 것은 자동화의 적이에요. 컴포즈 파일 내의 build 섹션을 활용해 변수를 주입받도록 설정해야 해요.

예를 들어, 빌드 시점에 특정 버전을 지정하거나 환경 변수를 전달하고 싶다면 args 옵션을 사용하세요.

# docker-compose.yml 예시
services:r
  web:r
    build:r
      context: .r
      dockerfile: Dockerfile.prodr
      args:r
        - APP_VERSION=${APP_VERSION:-latest}r
        - BUILD_ENV=${BUILD_ENV:-development}

위와 같이 설정하면, 실행 시점에 환경 변수를 통해 빌드 옵션을 제어할 수 있어요. 터미널에서 APP_VERSION=v1.2.0 BUILD_ENV=production docker-compose build라고 입력하면, 파일 내용을 수정하지 않고도 원하는 설정으로 빌드를 진행할 수 있죠. 이러한 방식은 나중에 CI/CD 도구와 연동될 때 매우 강력한 힘을 발휘해요.

STEP 3. 로컬 자동화를 위한 쉘 스크립트 작성

CI/CD를 구축하기 전, 개발자의 로컬 환경에서 반복되는 과정을 하나로 묶어주는 스크립트를 만드는 것이 좋아요. 단순히 명령어를 나열하는 것을 넘어, 빌드 전후의 상태를 체크하는 로직을 넣는 것이 핵심이에요.

#!/bin/bash
set -e

# 1. 환경 변수 로드
if [ -f .env ]; then
  export $(grep -v '^#' .env | xargs)
fi

echo "🚀 빌드 프로세스를 시작합니다... 버전: $APP_VERSION"

# 2. 이전 컨테이너 정지 및 정리 (필요 시)
# docker-compose down

# 3. 이미지 빌드
docker-compose build --no-cache

# 4. 컨테이너 실행 및 헬스체크 대기
docker-compose up -d

echo "✅ 배포가 완료되었습니다!"

이렇게 작성된 스크립트를 ./deploy.sh로 저장해두면, 복잡한 명령어를 외울 필요 없이 단 한 줄로 안전한 배포가 가능해져요.

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

이제 로컬 스크립트를 클라우드 환경으로 옮길 차례예요. GitHub Actions를 예로 들면, 코드가 메인 브랜치에 푸시될 때 자동으로 빌드와 배포가 일어나도록 설정할 수 있어요.

파이프라인은 크게 Build → Test → Push → Deploy의 흐름을 가져야 해요.

• Build & Test: 소스 코드를 가져와서 도커 이미지를 빌드하고, 간단한 유닛 테스트를 수행해요. 테스트가 실패하면 빌드 프로세스를 즉시 중단시켜 잘못된 이미지가 생성되는 것을 막아야 해요.
• Push: 빌드된 이미지를 Docker Hub나 AWS ECR 같은 이미지 레지스트리에 업로드해요. 이때 태그는 커밋 해시(Commit Hash)를 사용하여 각 빌드의 고유성을 보장하는 것이 좋아요.
• Deploy: 원격 서버에 접속하여 새로운 이미지를 Pull 받고, docker-compose up -d를 실행하여 서비스를 교체해요.

이 과정에서 가장 중요한 것은 보안이에요. 서버 접속을 위한 SSH 키나 도커 레지스트리 비밀번호는 절대 코드에 직접 적지 마세요. GitHub의 Secrets 기능을 사용하여 환경 변수로 안전하게 관리해야 해요.

STEP 5. 배포 검증 및 자동 롤백 설계

배포가 성공적으로 끝났다고 해서 안심하기엔 일러요. 컨테이너는 떴지만, 내부 애플리케이션이 에러를 뱉으며 무한 재시작 중일 수도 있으니까요. 그래서 Healthcheck 기능이 필수적이에요.

위와 같이 설정하면 도커 컴포즈가 컨테이너의 상태를 주기적으로 확인해요. 만약 헬스체크가 계속 실패한다면, 파이프라인 단계에서 이를 감지하고 자동으로 이전 버전의 이미지를 다시 띄우는 롤백 로직을 구현해야 해요. 롤백은 단순히 이전 명령어를 다시 치는 것이 아니라, 이미지 태그를 이전 커밋 해시로 되돌리는 것이어야 가장 빠르고 확실해요.
[실제 자동화 시나리오 예시]
1. 개발자가 `feature/login` 브랜치에 코드를 푸시함
2. GitHub Actions가 트리거되어 빌드 및 테스트 수행
3. 테스트 통과 시 `prod-image:a1b2c3d`라는 태그로 이미지를 레지스트리에 저장
4. 운영 서버에 SSH 접속 후 `docker-compose pull` 실행
5. 새 이미지로 교체 후 헬스체크 수행
6. 만약 헬스체크 실패 시, 즉시 `docker-compose up -d prod-image:old-hash` 실행하여 복구
자주 하는 실수와 해결법 및 FAQ
자동화 시스템을 구축하다 보면 예상치 못한 벽에 부딪히기 마련이에요. 많은 개발자가 공통적으로 겪는 실수들을 미리 파악해 두면 시행착오를 크게 줄일 수 있어요.
자주 하는 실수와 해결법
❌ 실수: .dockerignore를 설정하지 않아 빌드 속도가 너무 느림
왜 발생하는가: 빌드 시 로컬의 거대한 데이터나 라이브러리 폴더가 도커 데몬으로 전송되기 때문이에요.
✅ 해결법: 프로젝트 루트에 .dockerignore 파일을 만들고 node_modules, .git, 로그 파일 등을 반드시 명시하세요.
❌ 실수: 이미지 태그를 'latest'로만 사용함
왜 발생하는가: 어떤 버전이 배포되었는지 추적이 불가능하고, 문제가 생겼을 때 특정 시점으로 되돌리기가 매우 힘들어요.
✅ 해결법: Git 커밋 해시나 시멘틱 버저닝(v1.0.1 등)을 사용하여 각 빌드에 고유한 태그를 부여하세요.
❌ 실수: 빌드 시 환경 변수를 하드코딩함
왜 발생하는가: 보안상 위험할 뿐만 아니라, 개발/테스트/운영 환경마다 설정을 바꾸기 매우 어렵기 때문이에요.
✅ 해결법: .env 파일을 활용하거나 CI/CD 도구의 Secrets 기능을 사용하여 런타임에 값을 주입하세요.
❌ 실수: 빌드 아규먼트(args)와 환경 변수(env)를 혼동함
왜 발생하는가: 빌드 단계에서 필요한 값과 컨테이너 실행 단계에서 필요한 값을 구분하지 못했기 때문이에요.
✅ 해결법: 빌드 시점에 필요한 값은 args에, 실행 시 필요한 값은 environment에 정의하세요.
❌ 실수: 헬스체크 없이 배포를 완료함
왜 발생하는가: 컨테이너가 실행은 되었지만 내부 애플리케이션이 비정상 작동하는 경우를 잡아낼 수 없기 때문이에요.
✅ 해결법: docker-compose 파일에 반드시 healthcheck 옵션을 추가하여 서비스의 생존 여부를 확인하세요.
자주 묻는 질문
Q. 컴포즈 빌드 시 특정 레이어만 캐시를 무시하고 새로 빌드하고 싶어요. 어떻게 하나요?
A. 특정 단계부터 새로 빌드하고 싶다면 해당 부분의 명령어 앞에 --no-cache 옵션을 사용하거나, 빌드 아규먼트로 캐시를 깨뜨릴 수 있는 변수(예: BUILD_DATE)를 주입하는 방법을 추천해요.
Q. 여러 개의 도커파일을 하나의 컴포즈 파일에서 관리할 수 있나요?
A. 네, 가능해요! 서비스마다 build: dockerfile: Dockerfile.api와 같이 경로를 다르게 지정하면 각각 다른 도커파일을 사용하여 빌드할 수 있어요.
Q. .env 파일은 보안상 위험해 보이는데 어떻게 관리하는 게 좋을까요?
A. 로컬 개발 환경에서는 .env를 사용하되, Git에는 절대 올리지 마세요 (.gitignore 필수!). 운영 환경의 민감한 정보는 GitHub Secrets나 AWS Secrets Manager 같은 전문 관리 도구를 통해 CI/CD 파이프라인에 전달하는 것이 가장 안전해요.
Q. 빌드 컨텍스트를 줄이는 것만으로도 체감이 많이 되나요?
A. 네, 정말 커요! 특히 Node.js나 Python 프로젝트처럼 라이브러리 용량이 큰 경우, 불필요한 파일을 제외하는 것만으로도 빌드 시작 시간이 몇 분에서 몇 초로 줄어드는 경험을 할 수 있어요.
Q. CI/CD에서 배포 중 서버가 끊기면 어떻게 하나요?
A. 배포 프로세스를 원자적(Atomic)으로 설계해야 해요. 새 이미지를 먼저 Pull 받고, 컨테이너를 교체하는 순서로 진행하며, 실패 시 즉시 이전 이미지로 재실행하는 스크립트가 반드시 포함되어야 해요.
배포의 자유를 얻기 위한 여정의 시작
지금까지 컴포즈 build 옵션 자동화와 CI/CD 연동을 통해 수동 배포의 고통에서 벗어나는 방법을 상세히 살펴봤어요. 자동화는 한 번에 완성되는 거대한 성벽이 아니라, 매일 조금씩 쌓아 올리는 벽돌과 같아요. 처음에는 단순한 쉘 스크립트 하나로 시작하지만, 그것이 쌓여 견고한 파이프라인이 되고, 결국 여러분을 단순 반복 작업에서 해방시켜 줄 거예요.
✅ 핵심 요약


빌드 컨텍스트 최적화: .dockerignore를 사용하여 불필요한 파일 전송을 차단하세요.
유연한 설정: args와 .env를 활용해 환경별 빌드 옵션을 동적으로 제어하세요.
안전한 스크립트: set -e를 사용하여 에러 발생 시 즉시 중단되는 스크립트를 만드세요.
CI/CD 연동: 이미지 태그에 고유 값을 부여하고 Secrets로 보안을 강화하세요.
검증과 복구: Healthcheck를 통해 배포 성공을 확인하고 롤백 전략을 세우세요.


이제 이론은 충분해요. 실행이 답이에요. 오늘 바로 여러분의 터미널을 열고, 가장 자주 반복하는 명령 하나부터 스크립트로 옮겨 보는 건 어떨까요? 작은 자동화 하나가 여러분의 퇴근 시간을 30분 앞당겨 줄지도 몰라요.
🚀 다음 단계로 나아가기

오늘 할 일: 현재 프로젝트의 .dockerignore 파일 작성하기
이번 주 할 일: 주요 배포 명령어를 담은 deploy.sh 스크립트 완성하기
실행 직전 할 일: GitHub Actions에 빈 파이프라인 워크플로우 파일 만들어 보기

더 깊이 있는 도커 활용법이 궁금하다면, 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드를 참고해 보세요. 여러분의 안정적인 데브옵스 생활을 응원해요!