[IT-방법] 컴포즈 build 옵션 자동화와 CI/CD 연동 – 반복되는 배포 작업을 획기적으로 줄이는 전략

매번 반복되는 빌드 명령, 언제까지 직접 치실 건가요?

금요일 오후 퇴근을 앞두고 급하게 배포를 진행해야 하는 상황을 떠올려 보세요. 터미널을 열고 익숙하게 docker-compose build 명령어를 입력하려는데, 갑자기 기억이 가물가물해져요. “어제는 어떤 –build-arg를 추가했었지?” 혹은 “빌드 컨텍스트 경로를 어디로 지정했더라?” 하는 의문이 머릿속을 스칩니다.

결국 구버전 설정이나 잘못된 인자값을 입력해서 배포에 실패하고, 서버는 엉뚱한 이미지를 실행해요. 이런 실수는 단순히 귀찮은 문제를 넘어, 운영 환경의 장애로 이어지는 치명적인 사고가 될 수 있어요. 수동으로 입력하는 명령어 한 줄이 전체 시스템의 안정성을 흔드는 셈이에요.

이제는 손으로 직접 치는 방식에서 벗어나야 해요. 컴포즈 build 옵션 자동화는 단순한 편의 기능이 아니라, 데브옵스(DevOps) 환경을 구축하는 첫걸음이에요. 사람이 개입할 여지를 줄일수록 배포는 더 견고하고 예측 가능해져요.

이 글을 끝까지 읽고 나면 다음과 같은 능력을 갖추게 될 거예요.

• 도커 컴포즈의 빌드 옵션을 체계적으로 관리하는 방법
• 빌드 컨텍스트를 최적화하여 빌드 속도를 높이는 기술
• 스크립트와 CI/CD를 이용한 무인(Unattended) 배포 환경 구축
• 배포 실패 시 빠르게 원복하는 롤백 전략 설계

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

무작정 스크립트를 짜기 전에 현재의 배포 프로세스를 객관적으로 바라봐야 해요. 무엇을 자동화할지 결정하지 않으면, 오히려 관리해야 할 스크립트만 늘어나는 역효과가 발생할 수 있어요. 우선 build context와 build arguments의 개념을 명확히 구분하는 것부터 시작하세요.

자동화 대상 결정을 위한 준비물

자동화를 설계할 때는 다음 세 가지 요소가 준비되어 있어야 해요. 첫째는 현재 사용 중인 docker-compose.yml 파일의 완성도예요. 두 번째는 환경별로 달라지는 변수들을 관리할 .env 파일이나 시크릿 매니저(Secret Manager)예요. 마지막으로는 명령어를 실행할 주체인 쉘(Shell) 스크립트나 CI 도구(GitHub Actions, GitLab CI 등)의 접근 권한이에요.

운영 방식에 따른 자동화 수준 비교

현재 여러분의 팀이 어떤 단계에 있는지 아래 표를 통해 확인해 보세요. 목표는 단계적으로 올라가는 것이에요.

처음부터 거창한 CI/CD 파이프라인을 구축하려고 욕심내지 마세요. 우선 자주 사용하는 명령어 조합을 하나의 스크립트로 만드는 것만으로도 운영의 피로도는 절반 이하로 줄어들 수 있어요.

실전! 컴포즈 빌드 자동화 5단계 실행 가이드

이제 본격적으로 기술적인 구현 단계로 들어가 볼게요. 단순한 명령 실행을 넘어, 어떻게 하면 효율적이고 안전하게 컴포즈 build 옵션 자동화를 완성할 수 있는지 단계별로 상세히 설명해 드릴게요.

STEP 1. 빌드 인자(Build Args)와 환경 변수의 체계적 분리

많은 개발자가 실수하는 부분 중 하나가 빌드 타임에 필요한 값과 런타임에 필요한 값을 혼동하는 것이에요. build-arg는 이미지를 만드는 과정(Compile time)에 필요한 값이고, environment는 컨테이너가 실행된 후(Runtime)에 필요한 값이에요. 이를 자동화하려면 docker-compose.yml에서 다음과 같이 명확히 구분해야 해요.

예를 들어, 특정 버전의 라이브러리를 빌드에 포함해야 한다면 args 섹션을 사용하세요. 자동화 스크립트에서는 이 값을 .env 파일에서 읽어와 주입하도록 설계하는 것이 가장 깔끔해요. 이렇게 하면 코드 수정 없이 환경 변수 파일만 바꿔서 다양한 빌드 결과물을 만들어낼 수 있어요.

STEP 2. 빌드 컨텍스트 최적화로 속도와 보안 잡기

빌드 속도가 느리다면 90%의 확률로 빌드 컨텍스트가 너무 커서 발생하는 문제예요. 도커는 빌드를 시작할 때 지정된 경로의 모든 파일을 도커 데몬으로 전송해요. 만약 프로젝트 루트에 수백 메가바이트짜리 데이터 파일이나 .git 폴더가 있다면, 매번 이 거대한 데이터를 전송하느라 시간을 허비하게 돼요.

.dockerignore 파일을 반드시 활용하세요. 여기에 node_modules, .git, venv, 각종 로그 파일 등을 등록하면 전송되는 데이터 양이 획기적으로 줄어들어요. 이는 빌드 속도 향상은 물론, 민감한 설정 파일이 이미지 레이어에 포함되는 보안 사고를 막는 역할도 해요.

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

CI/CD로 가기 전, 로컬 환경에서 사용할 수 있는 자동화 스크립트를 만들어 보세요. 단순한 명령어 나열이 아니라, 조건문을 포함한 스마트한 스크립트가 필요해요. 아래는 서비스별로 빌드를 수행하는 간단한 시나리오 예시예요.

스크립트 내부 로직은 다음과 같이 설계하는 것이 좋아요.

1. 환경 변수 파일(.env)의 유효성을 검사해요.
2. 필요한 빌드 인자(Args)를 현재 시점에 맞게 생성해요.
3. docker compose build --no-cache [서비스명] 명령어를 실행하여 깨끗한 상태로 빌드해요.
4. 빌드가 성공하면 docker compose up -d로 교체 배포를 진행해요.

STEP 4. CI/CD 파이프라인 연동 (GitHub Actions 예시)

이제 스크립트를 클라우드로 옮길 차례예요. GitHub Actions를 사용한다면 workflow.yml 파일에 빌드 단계를 정의할 수 있어요. 여기서 핵심은 Docker Buildx를 사용하여 멀티 플랫폼 빌드를 지원하거나 캐시를 효율적으로 사용하는 것이에요.

파이프라인 설계 시, 빌드 단계와 배포 단계를 엄격히 분리하세요. 빌드 단계에서는 이미지를 생성하고 Docker Registry(예: Docker Hub, AWS ECR)에 푸시(Push)하는 작업만 수행해요. 이후 배포 단계에서 해당 태그를 가진 이미지를 가져와서 서버에 배포하는 방식이 가장 안전해요. 이렇게 하면 빌드 과정에서 발생한 오류가 운영 서버까지 침투하는 것을 원천 차단할 수 있어요.

STEP 5. 프로필(Profiles) 기능을 이용한 환경 분리

하나의 docker-compose.yml 파일로 개발(Dev), 테스트(Test), 운영(Prod) 환경을 모두 관리하고 싶다면 profiles 옵션을 사용하세요. 예를 들어, 운영 환경에서만 필요한 모니터링 도구나 디버깅 툴이 있다면 profiles: [debug]를 설정해 두세요. 자동화 스크립트에서 실행할 때 --profile debug를 붙이지 않으면 해당 서비스는 아예 생성되지 않아요. 이를 통해 환경별로 다른 빌드 옵션을 적용하는 복잡한 작업을 하나의 설정 파일로 깔끔하게 자동화할 수 있어요.

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

자주 하는 실수와 해결법

자동화 프로세스를 구축하다 보면 예상치 못한 곳에서 막히곤 해요. 실무에서 가장 많이 발생하는 사례들을 정리했어요.

• ❌ 실수: .dockerignore 없이 전체 폴더를 빌드 컨텍스트로 지정함
  → 왜 발생하는가: 귀찮아서 혹은 파일 구조를 잘 몰라서 그냥 루트 경로를 사용해요.
  → ✅ 해결법: 빌드에 불필요한 대용량 폴더와 로그, Git 이력을 제외하는 파일을 반드시 작성하세요.
• ❌ 실수: 빌드 인자(Args)를 환경 변수(Env)와 혼동함
  → 왜 발생하는가: 두 값이 결국 이미지에 영향을 준다고 생각하기 때문이에요.
  → ✅ 해결법: 빌드 시점에 결정될 값은 args에, 실행 시점에 결정될 값은 environment에 넣으세요.
• ❌ 실수: 자동화 스크립트에서 오류 발생 시에도 계속 진행함
  → 왜 발생하는가: 기본적으로 쉘은 명령어가 실패해도 다음 줄을 실행하기 때문이에요.
  → ✅ 해결법: 스크립트 상단에 set -e를 추가하여 즉시 중단되도록 만드세요.
• ❌ 실수: CI/CD 환경에서 이전 빌드 캐시를 전혀 활용하지 못함
  → 왜 발생하는가: 매번 완전한 빌드를 수행하도록 설정되어 있기 때문이에요.
  → ✅ 해결법: Docker 레이어 캐시 기능을 활성화하거나 Registry 캐시를 사용하도록 설정하세요.
• ❌ 실수: 민감한 정보를 docker-compose.yml에 직접 하드코딩함
  → 왜 발생하는가: 가장 빠르고 쉬운 방법이기 때문이에요.
  → ✅ 해결법: .env 파일이나 CI 도구의 Secrets 기능을 사용하세요.

자주 묻는 질문

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

build는 말 그대로 이미지를 생성하는 과정만 수행해요. 반면 up --build는 이미지를 새로 빌드한 다음, 그 이미지를 기반으로 컨테이너를 생성하고 실행까지 한 번에 진행해요. 개발 단계에서는 편리하지만, 운영 환경에서는 빌드와 실행을 분리하는 것이 훨씬 안전해요.

Q. 빌드 속도를 획기적으로 줄이는 가장 좋은 방법은 무엇인가요?

가장 효과적인 것은 레이어(Layer) 캐싱을 잘 활용하는 것이에요. Dockerfile 작성 시 변하지 않는 라이브러리 설치 명령(예: npm install, pip install)을 소스 코드 복사 명령보다 앞쪽에 배치하세요. 그래야 소스 코드가 바뀌어도 라이브러리 설치 레이어는 재사용될 수 있어요.

Q. 환경별로 다른 이미지를 만들어야 하는데 어떻게 자동화하나요?

이미지 태그를 활용하세요. 빌드 시점에 VERSION이나 ENV 변수를 인자로 받아 이미지 태그에 포함시키고(예: myapp:prod-v1.2), 이를 레지스트리에 푸시하면 환경별 관리가 매우 쉬워져요.

Q. 빌드 과정에서 오류가 나면 어떻게 대응해야 하나요?

자동화 파이프라인에 롤백 로직을 넣어야 해요. 빌드나 배포 단계가 실패하면, 기존에 떠 있던 이전 버전의 컨테이너를 그대로 유지하거나, 즉시 이전 이미지 태그로 다시 실행하도록 스크립트를 구성하세요.

Q. 컴포즈 프로필(Profiles)은 언제 쓰는 게 가장 좋나요?

로컬 개발 환경에서 데이터베이스 툴이나 모니터링 에이전트처럼 평소에는 필요 없지만 필요할 때만 띄워야 하는 서비스들을 관리할 때 가장 유용해요.

성공적인 자동화를 위한 체크리스트와 다음 단계

지금까지 컴포즈 build 옵션 자동화를 통해 운영 효율을 높이는 방법을 살펴봤어요. 자동화는 한 번에 완성되는 것이 아니라, 반복되는 문제를 하나씩 해결해 나가는 과정이에요. 오늘 배운 내용을 바탕으로 여러분의 작업 환경을 하나씩 개선해 보세요.

이제 무엇부터 해야 할지 고민된다면, 다음 단계를 따라가 보세요.

• 오늘 할 일: 현재 수동으로 입력하는 가장 긴 빌드 명령어를 메모장에 복사해 두세요.
• 이번 주 할 일: 그 명령어를 실행해 주는 아주 간단한 .sh 스크립트를 하나 만들어 보세요.
• 실행 직전 할 일: 스크립트에 set -e를 넣고, .dockerignore 파일이 제대로 작동하는지 확인하세요.

가장 자주 반복하는 명령 하나부터 스크립트로 옮겨 보세요. 작은 자동화가 모여 여러분의 소중한 퇴근 시간을 지켜줄 거예요. 더 깊이 있는 컨테이너 운영 기술이 궁금하다면 아래 가이드를 참고해 보세요.

관련 글: 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드