[IT-방법] 컴포즈 image 옵션 자동화 실무 가이드 – CI/CD 연동으로 배포 작업 줄이기

반복되는 배포 작업, 언제까지 수동으로 하실 건가요?

늦은 밤, 겨우 버그를 수정한 코드를 서버에 올리려고 터미널을 켭니다. 이미지를 새로 빌드하고, 레지스트리에 푸시한 뒤, 서버에 접속해 도커 컴포즈 명령어를 입력하는 과정을 수십 번 반복하다 보면 문득 이런 생각이 들어요. “이걸 매번 사람이 하고 있어야 하나?”

실제로 많은 개발자가 배포 과정에서 실수를 저지르곤 해요. 이미지 태그를 잘못 적거나, 이전 버전의 이미지를 그대로 사용하는 실수는 서비스 중단으로 이어질 수 있죠. 수동 배포는 단순히 귀찮은 문제가 아니라, 운영 안정성을 해치는 위험 요소예요.

특히 서비스 규모가 커지고 컨테이너 개수가 늘어나면, 사람이 일일이 컴포즈 파일을 수정하고 명령어를 치는 방식은 한계에 부딪혀요. 도커 컴포즈(Docker Compose)의 강력한 기능을 제대로 활용하지 못하고, 그저 컨테이너를 띄우는 용도로만 쓰고 있다면 시스템의 잠재력을 절반도 못 쓰고 있는 셈이에요.

이제는 도커 컴포즈의 image 옵션을 똑똑하게 활용해서, 코드만 올리면 배포까지 알아서 흐르는 환경을 만들어야 해요. 컴포즈 image 옵션 자동화를 구축하면 배포에 들어가는 정신적 에너지를 아껴서 더 가치 있는 코드 작성에 집중할 수 있어요.

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

• 자동화가 필요한 핵심 대상과 환경 설정 방법
• 환경 변수를 활용한 동적 이미지 태그 관리
• CI/CD 파이프라인에 컴포즈를 녹여내는 설계법
• 배포 실패 시 안전하게 되돌리는 롤백 전략
• 자동화 완성 후의 확장 가능한 로드맵

자동화 환경 구축을 위한 사전 준비 사항

무턱대고 스크립트부터 짜기 시작하면 나중에 구조가 꼬여서 고생하기 쉬워요. 자동화 시스템을 만들기 전에 반드시 갖춰져야 할 기반 시설이 몇 가지 있어요. 이 기반이 탄탄해야 나중에 파이프라인이 복잡해져도 무너지지 않아요.

1. 이미지 레지스트리와 인증 체계

자동화의 핵심은 CI/CD 도구가 빌드한 이미지를 서버가 문제없이 가져오는 거예요. 이를 위해 도커 허브(Docker Hub)나 AWS ECR 같은 레지스트리가 준비되어 있어야 해요. 여기서 중요한 건 인증(Authentication)이에요. 사람이 직접 로그인하는 게 아니라, 자동화 도구가 안전하게 접근할 수 있도록 서비스 계정(Service Account)이나 토큰(Token)을 미리 발급받아 두어야 해요.

2. 환경 변수 관리 전략

컴포즈 파일에 이미지 태그를 직접 적어두는 방식은 자동화에 적합하지 않아요. 버전이 바뀔 때마다 파일을 수정해야 하니까요. 대신 .env 파일을 사용하거나 시스템 환경 변수를 통해 이미지 태그를 외부에서 주입받는 구조를 만들어야 해요. 이것이 컴포즈 image 옵션 자동화의 시작점이에요.

3. CI/CD 도구 선택 기준

어떤 도구를 사용할지에 따라 스크립트의 형태가 완전히 달라져요. 현재 팀의 인프라 환경과 예산, 그리고 운영 난이도를 고려해서 선택해야 해요.

실전! 컴포즈 이미지 자동화 구축 5단계

준비가 끝났다면 이제 실제로 동작하는 파이프라인을 만들어 볼 차례예요. 단순히 명령어를 실행하는 것을 넘어, 변수와 스크립트를 결합하여 유연한 구조를 만드는 것이 핵심이에요.

STEP 1. 컴포즈 파일의 이미지 옵션 동적 설정

가장 먼저 해야 할 일은 docker-compose.yml 파일에서 이미지 이름을 고정하지 않는 것이에요. 태그 부분에 변수를 넣어주세요. 이렇게 하면 배포할 때마다 새로운 태그를 주입할 수 있어요.

services:
  web-app:
    image: my-registry.com/my-app:${APP_VERSION}
    ports:
      - "80:80"

여기서 ${APP_VERSION}이 핵심이에요. 이 변수는 실행 시점에 외부에서 주입될 예정이에요. 만약 이 값을 비워두면 컴포즈는 에러를 내거나 기본값을 찾으려 할 거예요. 따라서 반드시 환경 변수가 존재하도록 설계해야 해요.

STEP 2. 버전 관리를 위한 태그 전략 세우기

이미지 태그를 어떻게 붙이느냐에 따라 자동화의 난이도가 달라져요. 가장 피해야 할 것은 latest 태그를 사용하는 것이에요. latest를 쓰면 어떤 버전이 배포되었는지 추적하기 어렵고, 문제가 생겼을 때 롤백하기가 매우 까다로워요.

대신 다음과 같은 방식을 추천해요.

• Git Commit Hash 방식: app:a1b2c3d처럼 커밋 해시를 사용하는 방법이에요. 어떤 코드 상태가 배포되었는지 완벽하게 알 수 있어요.
• Semantic Versioning 방식: app:v1.2.3처럼 의미 있는 버전을 사용하는 방식이에요. 릴리즈 관리가 명확해져요.

실무에서는 Git Commit Hash를 사용하여 배포의 추적성을 확보하는 것이 가장 효율적이에요.

STEP 3. 배포 자동화 스크립트 작성

CI/CD 도구가 서버에 접속해서 실행할 명령어를 하나의 스크립트로 묶어두는 단계예요. 단순히 docker-compose up만 하는 게 아니라, 안전한 교체를 위한 일련의 과정이 필요해요.

#!/bin/bash
# deploy.sh

VERSION=$1
if [ -z "$VERSION" ]; then
  echo "에러: 버전을 입력해주세요 (예: ./deploy.sh a1b2c3d)"
  exit 1
fi

echo "배포 시작: 버전 $VERSION"
# 1. 새로운 이미지 가져오기
docker-compose pull
# 2. 컨테이너 재시작 (변경된 이미지 적용)
docker-compose up -d
# 3. 사용하지 않는 오래된 이미지 정리
docker image prune -f
echo "배포 완료!"

이 스크립트는 인자값으로 받은 버전을 바탕으로 동작해요. docker-compose pull을 먼저 실행해서 서버에 새 이미지를 미리 받아두는 것이 중요해요. 그래야 up 명령어를 실행했을 때 다운로드 시간 때문에 서비스가 끊기는 것을 최소화할 수 있어요.

STEP 4. GitHub Actions 파이프라인 연동

이제 작성한 스크립트를 클라우드 환경에서 자동으로 돌려볼게요. GitHub Actions를 예로 들면, 다음과 같은 흐름으로 워크플로우를 구성할 수 있어요.

1. Build & Push: 코드가 푸시되면 이미지를 빌드하고 태그를 붙여 레지스트리에 올려요.
2. SSH Connect: 빌드가 성공하면 대상 서버에 SSH로 접속해요.
3. Execute Script: 서버에 있는 배포 스크립트를 실행하며 방금 만든 태그를 전달해요.

STEP 5. 배포 검증 및 무중단 전략

배포가 끝났다고 해서 바로 끝난 게 아니에요. 컨테이너가 정상적으로 떴는지, 서비스가 요청을 잘 받는지 확인해야 해요. 헬스 체크(Health Check) 설정을 컴포즈 파일에 추가하는 것이 좋아요.

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost/" ]
  interval: 30s
  timeout: 10s
  retries: 3

이렇게 설정해두면, 도커는 컨테이너가 실제로 ‘준비 완료’ 상태가 될 때까지 기다려줘요. 만약 서비스가 뜨지 않는다면 배포 프로세스 단계에서 에러를 감지하고 중단할 수 있는 기반이 됩니다.

자주 하는 실수와 해결법

자동화 시스템을 처음 구축하면 예상치 못한 곳에서 문제가 터지곤 해요. 개발자들이 가장 흔히 겪는 문제들을 정리했어요.

• ❌ 실수: 이미지 태그를 latest로 설정함
  → 왜 발생하는가: 편리함 때문에 습관적으로 사용하지만, 이전 버전으로 돌아가기 매우 어려워져요.
  ✅ 해결법: Git 커밋 해시나 시맨틱 버전을 사용하여 고유한 태그를 사용하세요.
• ❌ 실수: 서버의 디스크 용량 부족
  → 왜 발생하는가: 새 이미지를 계속 받다 보면 오래된 이미지들이 쌓여 서버 용량을 다 잡아먹어요.
  ✅ 해결법: 배포 스크립트 마지막에 docker image prune -f 명령어를 넣어 불필요한 이미지를 주기적으로 삭제하세요.
• ❌ 실수: SSH 접속 권한 오류
  → 왜 발생하는가: CI/CD 도구가 서버에 접속할 때 사용하는 키가 서버의 authorized_keys에 등록되지 않았기 때문이에요.
  ✅ 해결법: CI/CD 전용 SSH 키를 생성하고, 필요한 권한만 부여하여 등록하세요.
• ❌ 실수: 환경 변수 주입 누락
  → 왜 발생하는가: 컴포즈 파일은 변수를 기다리는데, 실행 시점에 값을 넘겨주지 않으면 기본값으로 실행되어 엉뚱한 이미지가 배포돼요.
  ✅ 해결법: 스크립트 내에서 변수 존재 여부를 체크하는 로직을 반드시 넣으세요.
• ❌ 실수: 이미지 Pull 실패
  → 왜 발생하는가: 레지스트리 로그인 세션이 만료되었거나 권한이 없는 계정으로 접근을 시도했을 때 발생해요.
  ✅ 해결법: 배포 전 docker login 과정을 포함하거나, 서버에 이미 인증된 계정이 있는지 확인하세요.

자주 묻는 질문

Q. 컴포즈 이미지 자동화 시 가장 먼저 시작해야 할 것은 무엇인가요?

가장 먼저 현재 배포 과정을 단계별로 적어보세요. 어떤 명령어를 치는지, 어떤 파일이 바뀌는지 명확히 알아야 스크립트로 옮길 수 있어요. 그 다음 이미지 태그를 변수화하는 작업부터 시작하세요.

Q. 배포 중에 에러가 나면 어떻게 되나요?

자동화 스크립트 내에 에러 체크 로직이 있다면 배포 과정이 중단됩니다. 이때 exit 1을 사용하여 파이프라인을 실패 처리하도록 만들어야 해요. 그래야 담당자가 즉시 인지하고 조치할 수 있어요.

Q. .env 파일을 서버에 직접 올려도 안전한가요?

아니요, 매우 위험해요. .env에는 데이터베이스 비밀번호 같은 민감 정보가 들어있죠. 이런 정보는 CI/CD 도구의 Secret 기능을 사용해 실행 시점에 동적으로 생성하거나 주입하는 방식을 권장해요.

Q. 무중단 배포는 무조건 복잡한가요?

단순한 서비스라면 docker-compose up --scale 옵션을 활용해 컨테이너를 하나 더 띄우는 방식으로 어느 정도 대응할 수 있어요. 하지만 완벽한 무중단을 위해서는 로드 밸런서(Load Balancer)를 활용한 전략이 필요해요.

Q. 이미지 태그를 너무 많이 만들면 관리가 힘들지 않을까요?
매번 새로운 태그가 생기지만, 오히려 그 덕분에 문제가 생겼을 때 특정 시점으로 즉시 돌아갈 수 있는 ‘보험’을 드는 셈이에요. 관리는 주기적인 이미지 정리 명령어로 해결하면 됩니다.

자동화를 넘어 운영 효율화의 단계로

이제 단순히 명령어를 대신 입력해 주는 것을 넘어, 전체적인 시스템의 안정성을 높이는 방향으로 시야를 넓혀야 해요. 자동화는 끝이 아니라 새로운 운영의 시작이에요.

오늘 배운 내용을 바탕으로 바로 실행에 옮겨 보세요. 거창한 파이프라인이 아니어도 괜찮아요. 가장 자주 반복하는 명령 하나부터 스크립트로 옮겨 보세요. 그 작은 시작이 여러분의 퇴근 시간을 앞당겨 줄 거예요.

앞으로 나아갈 단계는 다음과 같아요.

• 오늘 할 일: 현재 사용 중인 docker-compose.yml의 이미지 부분을 변수로 변경해 보기
• 이번 주 할 일: 배포 과정을 담은 간단한 쉘 스크립트 작성하고 로컬에서 테스트하기
• 실행 직전 할 일: GitHub Actions나 Jenkins에 스크립트 연동 및 보안 설정 완료하기

자동화가 익숙해졌다면, 다음에는 모니터링 도구를 연동해 배포 직후의 시스템 상태를 자동으로 리포팅하는 단계로 넘어가 보시길 추천해요.

관련해서 더 깊은 기초 지식이 필요하다면 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드를 먼저 읽어보시면 큰 도움이 될 거예요.