[IT-방법] 컴포즈 build 옵션 자동화와 CI/CD 연동 – 반복적인 수동 배포에서 벗어나는 기술

반복되는 수동 배포, 언제까지 명령어를 직접 입력할 건가요?

퇴근 직전, 마지막으로 코드 한 줄을 수정하고 서버에 반영하려고 터미널을 열어요. docker-compose build 명령어를 치고, 각종 빌드 인자를 하나하나 입력하다 보면 문득 이런 생각이 들어요. “이걸 매번 내가 직접 타이핑해야 하나?”

단순히 명령어를 입력하는 것이 문제가 아니에요. 빌드 옵션 하나를 잘못 입력하거나, 빌드 컨텍스트 경로를 실수로 지정하면 배포는 실패하고 서버 환경은 꼬이기 시작해요. 사람이 하는 일이라 실수는 피할 수 없지만, 그 실수가 서비스 장애로 이어진다면 이야기는 달라져요. 수동 배포는 단순 반복을 넘어 운영의 불안정성을 키우는 가장 큰 원인이에요.

이제는 명령어를 외우는 단계에서 벗어나야 해요. 배포 환경을 코드로 정의하고, 시스템이 스스로 빌드하고 배포하도록 만드는 과정이 필요해요. 컴포즈 build 옵션 자동화는 단순한 편의를 넘어, 데브옵스(DevOps)의 첫걸음이자 안정적인 서비스를 운영하기 위한 필수 생존 전략이에요.

이 글을 끝까지 읽고 나면 다음과 같은 역량을 갖추게 돼요.

• 도커 컴포즈의 빌드 옵션을 정밀하게 제어하는 방법
• 환경별로 다른 빌드 컨텍스트를 안전하게 관리하는 요령
• CI/CD 파이프라인에 빌드 과정을 녹여내는 실무 프로세스
• 배포 실패 시 시스템을 안전하게 복구하는 전략

자동화 시작 전, 반드시 짚고 넘어가야 할 핵심 개념

무작정 스크립트를 짜기 전에, 우리가 자동화하려는 대상이 무엇인지 명확히 정의해야 해요. 도커 컴포즈에서 빌드 과정은 단순히 이미지를 만드는 행위 그 이상을 포함해요. 어떤 파일을 빌드 환경에 포함할지, 어떤 설정값을 주입할지를 결정하는 설계 과정이 선행되어야 하거든요.

빌드 자동화를 위한 3가지 필수 요소

성공적인 자동화를 위해서는 다음 세 가지 요소가 유기적으로 연결되어야 해요. 첫 번째는 빌드 컨텍스트(Build Context)예요. 빌드 시 도커 데몬에 전달되는 파일의 범위를 의미하는데, 이 범위가 너무 넓으면 빌드 속도가 느려지고 보안상 위험할 수 있어요. 두 번째는 빌드 인자(Build Args)예요. 환경 변수처럼 빌드 시점에 동적으로 값을 넘겨주는 장치죠. 마지막은 도커파일(Dockerfile)의 구조예요. 자동화가 원활하려면 도커파일이 가변적인 환경에 유연하게 대응할 수 있도록 작성되어야 해요.

운영 환경에 따른 빌드 방식 비교

모든 프로젝트에 무거운 CI/CD 도구가 필요한 것은 아니에요. 현재 팀의 규모와 프로젝트의 복잡도에 맞는 방식을 선택하는 것이 효율적이에요.

만약 현재 매일 아침 출근해서 수동으로 명령어를 입력하고 있다면, 우선 쉘 스크립트로 넘어가고, 그 다음 단계로 GitHub Actions 같은 도구를 도입하는 순차적인 접근을 추천해요.

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

이제 이론을 넘어 실제로 어떻게 자동화를 구축하는지 단계별로 살펴볼게요. 이 과정은 로컬 환경에서의 최적화부터 클라우드 기반의 완전 자동화까지를 모두 포괄해요.

STEP 1. 도커 컴포즈 빌드 옵션의 정밀 설계

자동화의 첫 단추는 docker-compose.yml 파일 내의 build 섹션을 완벽하게 구성하는 것이에요. 단순히 build: .라고 적는 것은 자동화의 잠재력을 낭비하는 것이에요.

효율적인 자동화를 위해 다음과 같은 구성을 권장해요. 먼저 context는 프로젝트의 루트 디렉토리로 설정하되, dockerfile 경로를 명시하여 여러 개의 도커파일을 운영할 수 있게 만드세요. 또한 args 항목을 통해 환경 변수를 주입할 준비를 마쳐야 해요.

이렇게 설정해 두면, 나중에 자동화 도구가 환경에 맞는 파일을 선택해서 실행하기만 하면 되거든요.

STEP 2. 환경 변수를 활용한 빌드 컨텍스트 최적화

빌드할 때마다 파일이 바뀌거나 설정이 달라진다면, 이를 자동화 도구가 읽을 수 있는 형태로 만들어야 해요. 이때 가장 강력한 도구가 .env 파일이에요. .env 파일에 정의된 변수는 도커 컴포즈가 실행될 때 자동으로 읽혀서 빌드 인자로 전달될 수 있어요.

예를 들어, 애플리케이션의 버전을 `APP_VERSION=1.2.3`으로 지정해 두었다면, 도커파일 내부에서 ARG APP_VERSION을 선언하여 이 값을 사용할 수 있어요. 이렇게 하면 소스 코드를 수정하지 않고도 .env 파일만 바꿔서 빌드 결과물을 제어할 수 있는 구조가 완성돼요.

STEP 3. 쉘 스크립트를 이용한 로컬 자동화 기초 구축

CI/CD를 도입하기 전, 가장 먼저 해야 할 일은 자주 쓰는 명령어를 하나의 파일로 묶는 것이에요. deploy.sh 같은 이름의 스크립트를 만들어 보세요. 이 스크립트는 단순히 명령어를 나열하는 것을 넘어, 논리적인 흐름을 가져야 해요.

• 먼저, 현재 Git 브랜치를 확인하여 허용된 브랜치인지 검증해요.
• 그 다음, docker-compose pull을 통해 최신 이미지를 가져와요.
• 이어서 docker-compose build --build-arg VERSION=$VERSION를 실행해요.
• 마지막으로 컨테이너를 재시작하고 로그를 출력하며 마무리해요.

이렇게 스크립트화된 명령어는 실수할 확률을 0%에 가깝게 줄여줘요. 사람이 직접 입력할 때 생기는 오타나 순서 오류를 원천 봉쇄할 수 있기 때문이죠.

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

이제 진정한 자동화의 단계예요. 코드가 메인 브랜치에 Push되는 순간, 클라우드 서버가 알아서 빌드하고 배포하는 환경을 구축해 볼게요. GitHub Actions를 예로 들면, workflow 파일을 작성해야 해요.

파이프라인은 보통 Build $\rightarrow$ Test $\rightarrow$ Push $\rightarrow$ Deploy 순서로 진행돼요. 빌드 단계에서는 앞서 설계한 build 옵션을 사용하여 이미지를 생성하고, 테스트 단계에서 유닛 테스트를 통과하는지 확인해요. 테스트가 성공하면 Docker Hub나 AWS ECR 같은 레지스트리에 이미지를 업로드(Push)하고, 최종적으로 운영 서버에 접속하여 새로운 이미지를 내려받아 실행(Deploy)하도록 구성해요.

이 과정이 완성되면 개발자는 더 이상 배포를 걱정할 필요가 없어요. 단지 코드를 작성하고 Push하는 것에만 집중하면 되니까요.

STEP 5. 이미지 태깅 전략과 롤백 시나리오 설계

자동화가 완성되었다고 끝이 아니에요. 빌드된 이미지를 어떻게 이름 붙일지, 그리고 배포가 실패했을 때 어떻게 되돌릴지가 핵심이에요. 이미지 태그로 단순히 latest만 사용하면 절대 안 돼요. Semantic Versioning(SemVer)을 따라 `v1.0.1`, `v1.0.2`처럼 구체적인 태그를 붙여야 해요.

태그가 구체적이어야 배포 중 문제가 생겼을 때 즉시 이전 버전의 이미지로 되돌리는(Rollback) 작업이 가능해져요. 예를 들어, `v1.1.0` 배포 후 에러가 발견되면, 즉시 명령어를 통해 `v1.0.9` 이미지를 실행하도록 스크립트를 짜두는 것이죠. 이것이 바로 운영 환경에서 살아남는 베테랑의 노하우예요.

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

자주 하는 실수와 해결법

자동화 과정에서 누구나 한 번쯤 겪게 되는 골치 아픈 문제들을 정리했어요. 문제를 미리 알고 있다면 당황하지 않고 해결할 수 있어요.

• ❌ 빌드 컨텍스트 경로 오류 $\rightarrow$
  왜 발생하는가: 도커파일 위치와 실제 파일 경로가 일치하지 않아서 발생해요.
  ✅ 해결법: docker-compose.yml의 context와 dockerfile 경로를 절대 경로가 아닌 프로젝트 루트 기준 상대 경로로 다시 확인하세요.
• ❌ 캐시로 인한 업데이트 미반영 $\rightarrow$
  왜 발생하는가: 도커가 이전 빌드 레이어를 재사용하면서 최신 코드가 반영되지 않아요.
  ✅ 해결법: 빌드 명령어 뒤에 --no-cache 옵션을 붙여 강제로 새로 빌드하도록 설정하세요.
• ❌ Build Arg 전달 누락 $\rightarrow$
  왜 발생하는가: 쉘 환경 변수는 정의했지만, 도커파일 내부에서 ARG 선언을 하지 않아 값이 유실돼요.
  ✅ 해결법: 도커파일 상단에 사용할 변수를 ARG 키워드로 반드시 선언해 주세요.
• ❌ CI/CD 권한 에러 $\rightarrow$
  왜 발생하는가: 자동화 도구가 서버에 접속할 수 있는 SSH 키나 권한이 부족해요.
  ✅ 해결법: 배포용 서비스 계정을 별도로 만들고, 필요한 최소 권한만 부여한 뒤 인증 정보를 보안 저장소에 등록하세요.
• ❌ 이미지 용량 과다 $\rightarrow$
  왜 발생하는가: 불필요한 라이브러리와 빌드 도구가 이미지에 포함되어 배포 속도가 느려져요.
  ✅ 해결법: Multi-stage Build 기법을 사용하여 최종 이미지에는 실행에 필요한 파일만 남기도록 설계하세요.

자주 묻는 질문

Q. 빌드 속도가 너무 느린데, 어떻게 개선할 수 있을까요?

먼저 .dockerignore 파일을 통해 빌드에 필요 없는 파일들을 제외하고 있는지 확인하세요. 또한, 도커파일 작성 시 자주 바뀌지 않는 명령(예: 패키지 설치)을 위쪽에 배치하여 레이어 캐시를 최대한 활용하는 것이 핵심이에요.

Q. 환경 변수를 빌드 시점에 넣는 것과 컨테이너 실행 시점에 넣는 것의 차이가 뭔가요?

매우 중요한 질문이에요. Build Args는 이미지를 만드는 과정(Compile time)에 고정되는 값이고, Env Vars는 컨테이너가 뜰 때(Runtime) 결정되는 값이에요. 보안이 중요한 데이터나 환경마다 매번 바뀌는 값은 반드시 실행 시점 변수로 처리해야 해요.

Q. 도커 컴포즈 파일이 너무 많아지면 관리가 힘들어요. 팁이 있을까요?

파일을 쪼개는 것이 답이에요. 기본 설정은 `docker-compose.yml`에 두고, 개발용이나 테스트용 설정은 `docker-compose.override.yml` 등을 활용해 덮어쓰는 방식을 사용하세요. 이렇게 하면 공통된 부분은 유지하면서 환경별 차이점만 깔끔하게 관리할 수 있어요.

Q. CI/CD 도중 빌드가 성공했는데 배포가 안 돼요. 어디를 봐야 하죠?

대부분 네트워크나 권한 문제예요. CI/CD 서버에서 운영 서버로 접속할 때 사용하는 SSH 키가 유효한지, 혹은 서버의 디스크 공간이 꽉 차서 새로운 이미지를 받을 수 없는 상태는 아닌지 확인해 보세요.

이제 당신의 배포는 시스템이 책임집니다

수동으로 명령어를 입력하며 긴장하던 시간은 이제 지나갔어요. 자동화는 단순히 일을 대신 해주는 것이 아니라, 우리가 더 가치 있는 코드 작성과 아키텍처 설계에 집중할 수 있는 시간을 벌어다 주는 도구예요. 오늘 배운 내용을 바탕으로 하나씩 시스템을 구축해 보세요.

지금 바로 무엇부터 시작해야 할지 막막하다면, 다음의 단계별 행동 계획을 따라가 보세요.

• 오늘 할 일: 현재 가장 자주 반복하는 도커 명령어들을 메모장에 적어보고, 이를 하나의 쉘 스크립트로 묶어보세요.
• 이번 주 할 일: GitHub Actions나 GitLab CI를 활용해 코드 Push 시 이미지가 빌드되는 간단한 파이프라인을 구축해 보세요.
• 실행 직전 할 할 일: 배포 중 문제가 생겼을 때 이전 이미지로 즉시 되돌릴 수 있는 태그 규칙을 정하고 테스트해 보세요.

작은 스크립트 하나가 거대한 운영 자동화의 시작이 됩니다. 가장 자주 반복하는 명령 하나부터 스크립트로 옮겨 보세요. 그 순간부터 당신의 데브옵스 여정이 시작될 거예요.

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