[IT-방법] 컴포즈 build 옵션 자동화와 CI/CD 연동 – 반복적인 배포 명령을 스크립트로 해결하는 방법

매번 반복하는 build 명령어가 버거운 개발자를 위하여

금요일 오후, 배포를 앞두고 터미널에 익숙한 명령어를 입력해요. docker-compose build 뒤에 수많은 –build-arg 옵션을 붙이고, 빌드 컨텍스트 경로를 확인하며 긴장된 마음으로 엔터를 눌러요. 하지만 실수로 환경 변수 하나를 잘못 입력하거나, 컨텍스트 경로를 한 글자 틀리는 순간 배포 프로세스는 엉망이 되고 말아요.

이런 경험은 단순히 귀찮은 문제를 넘어, 서비스 운영의 안정성을 위협하는 커다란 리스크가 돼요. 사람이 직접 명령어를 입력하는 순간, 실수는 반드시 발생하기 마련이니까요. 반복되는 수동 배포는 개발자의 집중력을 앗아가고, 결국 더 중요한 설계나 기능 구현에 쏟아야 할 시간을 낭비하게 만들어요.

이제는 컴포즈 build 옵션 자동화를 통해 이 굴레에서 벗어나야 해요. 단순히 명령어를 복사해서 붙여넣는 수준을 넘어, 시스템이 알아서 최적의 빌드 환경을 구성하고 검증까지 마치는 구조를 만들어야 하죠. 이 글을 끝까지 읽고 나면, 손으로 직접 치던 명령어를 지우고 파이프라인에 배포를 맡기는 즐거움을 느끼실 수 있어요.

이 글에서는 다음과 같은 내용을 깊이 있게 다뤄요.

• 수동 배포가 왜 위험하고 자동화가 필요한지
• 자동화를 위해 미리 준비해야 할 핵심 설정들
• 실전 빌드 스크립트와 CI/CD 파이프라인 설계법
• 배포 실패 시 안전하게 되돌리는 롤백 전략

자동화의 시작, 핵심 개념과 준비물 체크리스트

자동화 시스템을 구축하기 전에 반드시 짚고 넘어가야 할 개념이 있어요. 가장 먼저 이해해야 할 것은 빌드 컨텍스트(Build Context)예요. 빌드 컨텍스트는 도커 데몬이 빌드 과정에서 접근할 수 있는 파일들의 범위를 의미해요. 이 범위가 너무 넓으면 빌드 속도가 느려지고, 너무 좁으면 필요한 파일을 찾지 못해 에러가 발생하죠.

또한, build-arg를 어떻게 관리할지도 결정해야 해요. 빌드 시점에 필요한 변수들을 명령줄에 직접 입력하는 방식은 자동화에 매우 부적합해요. 대신 환경 변수 파일이나 CI/CD 도구의 비밀 변수(Secrets) 기능을 활용하는 방향으로 설계해야 안전하고 효율적이에요.

자동화 방식을 선택할 때는 현재 팀의 규모와 배포 빈도를 고려해야 해요. 아래 표를 통해 본인에게 가장 적합한 방식이 무엇인지 비교해 보세요.

초기에는 쉘 스크립트로 시작하는 것이 가장 현실적이에요. 모든 것을 한 번에 CI/CD로 옮기려고 하면 설정의 복잡함 때문에 포기하기 쉽거든요. 우선 자주 사용하는 docker-compose build 옵션들을 하나의 파일로 묶는 작업부터 시작해 보세요.

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

이제 이론을 넘어 실제로 동작하는 자동화 시스템을 만들어볼 시간이에요. 단순히 명령어를 묶는 것이 아니라, 어떤 상황에서도 견고하게 동작하는 파이프라인을 설계하는 것이 목표예요. 총 5단계의 과정을 거쳐 완성해 볼게요.

STEP 1. 도커 컴포즈 설정 최적화하기

자동화의 첫 단추는 docker-compose.yml 파일을 똑똑하게 작성하는 거예요. 빌드 옵션을 하드코딩하지 말고, 환경 변수를 적극적으로 활용해야 해요. 예를 들어, 서비스마다 다른 빌드 인자를 전달해야 한다면 아래와 같이 설정할 수 있어요.

설정 파일에서 args 항목을 사용하여 변수를 정의해 두면, 나중에 스크립트에서 이 값만 갈아 끼우면 돼요. 이렇게 하면 동일한 컴포즈 파일로 개발, 테스트, 운영 환경을 모두 커버할 수 있죠.

STEP 2. 쉘 스크립트로 명령 체계 일원화하기

매번 긴 옵션을 입력하는 대신, 실행 가능한 스크립트 파일을 만드세요. 예를 들어 deploy.sh라는 파일을 만들고, 그 안에 빌드와 실행 명령을 논리적인 순서로 배치하는 거예요. 스크립트에는 단순히 명령어만 넣는 게 아니라, 빌드 전 기존 이미지를 정리하거나 환경 변수 파일(.env)을 생성하는 로직도 포함되어야 해요.

스크립트를 작성할 때는 에러 핸들링이 생명이에요. 명령어가 하나라도 실패하면 즉시 중단되도록 set -e 옵션을 반드시 최상단에 넣어주세요. 빌드가 실패했는데 그다음 단계인 배포가 진행된다면, 서비스 전체가 다운되는 대참사가 발생할 수 있으니까요.

STEP 3. CI/CD 파이프라인 구축하기 (GitHub Actions 예시)

스크립트가 로컬에서 잘 돌아간다면, 이제 이를 클라우드 환경으로 옮길 차례예요. 가장 대중적인 GitHub Actions를 예로 들어볼게요. 코드 저장소에 푸시가 발생하면 자동으로 워크플로우가 시작되도록 설정하는 거죠. 이 단계에서는 다음의 순서로 작업을 수행해요.

1. 코드가 메인 브랜치에 병합되었는지 확인해요.
2. 빌드에 필요한 환경 변수와 비밀 값을 가져와요.
3. 도커 이미지를 빌드하고, 지정된 빌드 컨텍스트를 사용해요.
4. 빌드된 이미지를 도커 레지스트리(Docker Hub, ECR 등)에 업로드(Push)해요.

이 과정이 완료되면 개발자는 더 이상 터미널을 열 필요가 없어요. 코드를 푸시하는 것만으로 모든 배포 과정이 자동으로 진행되죠. 이때 Multi-stage build 기법을 사용하면 이미지 크기를 획기적으로 줄여 배포 속도까지 높일 수 있어요.

STEP 4. 환경별 설정 관리와 .env 활용

운영 서버와 개발 서버는 빌드 옵션이 다를 수밖에 없어요. 이를 위해 환경별로 별도의 .env 파일을 관리하는 전략이 필요해요. 자동화 스크립트가 실행될 때 현재 환경이 무엇인지 판단하고, 그에 맞는 설정 파일을 불러오도록 설계해야 하죠.

주의할 점은 보안이에요. 데이터베이스 비밀번호나 API 키 같은 민감한 정보가 절대 깃허브 저장소에 올라가면 안 돼요. 이런 정보들은 반드시 CI/CD 도구의 Secrets 설정을 통해 주입해야 한다는 점을 잊지 마세요.

STEP 5. 배포 검증 및 모니터링 자동화

빌드가 끝났다고 해서 모든 것이 끝난 건 아니에요. 컨테이너가 실제로 정상적으로 떴는지, 헬스 체크(Health Check)를 통과했는지 확인하는 단계가 반드시 필요해요. 스크립트 마지막 부분에 docker-compose ps 명령어를 넣어 상태를 출력하거나, 특정 API 엔드포인트에 요청을 보내 응답이 오는지 확인하는 로직을 추가하세요.

만약 헬스 체크에 실패한다면, 시스템은 즉시 관리자에게 알림을 보내야 해요. 이 단계까지 마쳐야 비로소 ‘손을 놓을 수 있는’ 진정한 자동화가 완성되었다고 말할 수 있어요.

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

자동화 시스템을 구축하다 보면 예상치 못한 변수들 때문에 머리가 아픈 순간이 오기 마련이에요. 흔히 발생하는 문제들과 그 해결책을 정리해 두었으니, 문제가 생기면 바로 확인해 보세요.

자주 하는 실수와 해결법

❌ 실수: 빌드 컨텍스트가 너무 커서 빌드가 매우 느려짐
왜 발생하는가: 프로젝트 폴더 전체를 빌드 컨텍스트로 잡아서 불필요한 데이터(node_modules, 로그, 데이터 파일 등)까지 모두 도커 데몬으로 전송하기 때문이에요.
✅ 해결법: 반드시 .dockerignore 파일을 작성하여 빌드에 필요 없는 파일들을 제외하세요.

❌ 실수: 환경 변수가 빌드 시점에 반영되지 않음
왜 발생하는가: 컴포즈 파일의 environment 섹션은 컨테이너 실행 시점에 적용되는 것이고, 빌드 시점에 값을 넣으려면 build-arg를 사용해야 하기 때문이에요.
✅ 해결법: Dockerfile 내부에 ARG 명령어를 선언하고, 컴포즈 파일의 build 섹션에서 args로 값을 넘겨주세요.

❌ 실수: 이전 빌드 캐시 때문에 변경 사항이 반영되지 않음
왜 발생하는가: 도커의 레이어 캐싱 기능이 의도치 않게 이전 상태를 유지하고 있기 때문이에요.
✅ 해결법: 특정 단계에서 강제로 새로 빌드하고 싶다면 --no-cache 옵션을 사용하거나, 캐시를 깨뜨릴 수 있는 환경 변수를 빌드 인자로 활용하세요.

❌ 실수: CI/CD에서 권한 문제로 이미지를 Push하지 못함
왜 발생하는가: CI/CD 실행 환경(Runner)에 도커 레지스트리에 접근할 수 있는 로그인 정보가 없기 때문이에요.
✅ 해결법: CI/CD 설정 단계에서 docker login 명령을 실행하거나, 공식 액션(Action)을 사용하여 인증을 처리하세요.

❌ 실수: 빌드 스크립트가 중간에 실패해도 배포가 진행됨
왜 발생하는가: 스크립트 내 명령어가 실패해도 다음 줄이 계속 실행되도록 설정되어 있기 때문이에요.
✅ 해결법: 스크립트 시작 부분에 set -e를 추가하여 에러 발생 시 즉시 중단되도록 만드세요.

자주 묻는 질문

Q. 컴포즈 build 옵션 자동화가 정말 보안상 안전한가요?

직접 명령어를 입력하는 것보다 훨씬 안전해요. 자동화 도구(GitHub Actions 등)의 암호화된 Secret 기능을 사용하면, 민감한 정보가 로그에 남거나 코드에 노출될 위험을 원천적으로 차단할 수 있기 때문이에요.

Q. 빌드 속도를 더 높일 수 있는 팁이 있을까요?
가장 효과적인 방법은 Multi-stage 빌드를 사용하는 거예요. 빌드 도구가 포함된 무거운 이미지는 빌드 단계에서만 사용하고, 최종 결과물은 가벼운 런타임 이미지만 사용하여 이미지 크기를 줄이고 전송 속도를 높일 수 있어요.

Q. .env 파일을 깃허브에 올려도 되나요?
절대 안 돼요! 보안의 가장 기본은 민감 정보를 코드 저장소에 올리지 않는 것이에요. .env 파일은 .gitignore에 등록하고, 필요한 값은 CI/CD 환경 설정에서 직접 입력해 주세요.

Q. 쉘 스크립트와 CI/CD 중 무엇을 먼저 공부해야 할까요?
쉘 스크립트를 먼저 익히는 것을 추천해요. CI/CD 도구는 결국 내부적으로 쉘 명령어를 실행하는 구조이기 때문에, 스크립트 능력이 탄탄해야 복잡한 파이프라인도 자유자재로 설계할 수 있어요.

자동화로 확보한 시간, 이제 더 가치 있는 일에 쓰세요

지금까지 컴포즈 build 옵션 자동화와 CI/CD 연동을 위한 핵심 전략들을 살펴보았어요. 처음에는 설정을 구성하는 과정이 번거롭고 복잡하게 느껴질 수 있어요. 하지만 한 번 제대로 구축해 놓은 자동화 시스템은 여러분의 퇴근 시간을 앞당겨주고, 배포에 대한 불안감을 확신으로 바꿔줄 거예요.

자동화는 한 번에 완성되는 것이 아니라, 운영하면서 계속해서 다듬어가는 과정이에요. 오늘 당장 여러분이 가장 자주 반복하는 명령어 딱 하나부터 스크립트로 옮겨 보는 것은 어떨까요? 작은 변화가 모여 거대한 생산성의 차이를 만들어낼 거예요.

🚀 다음 단계로 나아가기

• 오늘 할 일: 자주 쓰는 build 명령어들을 모아 간단한 .sh 파일 만들기
• 이번 주 할 일: .dockerignore 파일을 작성하여 빌드 속도 측정해 보기
• 실행 직전 할 일: GitHub Actions 워크플로우 기본 템플릿 살펴보기

더 깊이 있는 컨테이너 운영 지식이 필요하다면, 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드 글을 함께 읽어보시는 것을 추천해요.