[IT-방법] 컴포즈 services 자동화와 CI/CD 연동 – 반복 배포에서 해방되는 실무 가이드

매번 수동으로 배포하며 불안해하고 있지는 않나요?

퇴근을 코앞에 둔 금요일 저녁, 갑자기 서버에 에러 로그가 쌓이기 시작해요. 떨리는 손으로 터미널에 접속해서 docker-compose pull을 입력하고, 다시 docker-compose up -d를 실행하죠. 그런데 이번에는 웬걸, 환경 변수 하나를 빼먹어서 서비스가 다시 죽어버려요. 이런 경험, 개발자라면 한 번쯤은 겪어보셨을 거예요.

단순히 명령어를 몇 번 더 치는 게 문제가 아니에요. 사람이 직접 개입하는 순간, 반드시 실수가 생길 수밖에 없거든요. 오타 하나, 설정 파일 누락 하나가 전체 시스템을 마비시킬 수 있다는 압박감은 생각보다 정말 커요. 매번 같은 과정을 반복하며 에너지를 낭비하는 건 우리 커리어에도 결코 도움이 되지 않아요.

그래서 이제는 컴포즈 services 자동화가 반드시 필요해요. 단순히 명령어를 대신 실행해 주는 것을 넘어, 배포 과정 전체를 하나의 안전한 파이프라인으로 구축해야 해요. 자동화가 잘 구축되어 있으면 코드를 푸시하는 것만으로도 검증부터 배포, 그리고 문제 발생 시 복구까지 시스템이 알아서 처리해 주니까요.

이 글에서는 단순히 도커 명령어를 나열하는 수준을 넘어, 실무에서 바로 써먹을 수 있는 자동화 전략을 다뤄요.

• 수동 배포가 가진 치명적인 위험성과 자동화의 필요성
• 자동화를 위해 미리 갖춰야 할 환경과 선택 기준
• 스크립트부터 CI/CD 파이프라인까지 이어지는 단계별 설계법
• 배포 실패 시 시스템을 안전하게 돌리는 롤백 전략

자동화로 가기 전, 반드시 점검해야 할 체크리스트

무턱대고 자동화 도구부터 도입한다고 해서 모든 문제가 해결되지는 않아요. 오히려 준비 없이 시작했다가는 자동화된 스크립트가 잘못된 설정을 서버에 순식간에 퍼뜨리는 재앙을 맞이할 수도 있거든요. 기반이 탄탄해야 자동화도 안전해요.

먼저 우리가 다루는 도커 컴포즈 파일 자체가 표준화되어 있는지 확인해야 해요. 서비스마다 환경 변수를 다루는 방식이 제각각이거나, 볼륨 경로가 절대 경로로 엉망으로 꼬여 있다면 자동화 스크립트를 짜는 것 자체가 불가능에 가까워요. 모든 서비스가 동일한 규칙을 따르고 있는지부터 살펴보세요.

다음은 여러분의 현재 상황에 맞는 자동화 수준을 결정하기 위한 비교표예요. 우리 팀의 리소스와 서비스의 중요도에 맞춰 어떤 단계를 목표로 할지 결정해 보세요.

위 표를 보면 알 수 있듯이, 처음부터 거창한 CI/CD 파이프라인을 구축하려고 욕심내지 마세요. 우선은 자주 쓰는 명령어를 모아 쉘 스크립트로 만드는 것부터 시작하는 게 현명해요. 그 후에 점진적으로 도구를 확장해 나가는 것이 실패를 줄이는 가장 좋은 방법이에요.

준비물로는 도커 컴포즈가 설치된 서버, 코드가 관리되는 Git 저장소, 그리고 배포 명령을 전달할 수 있는 SSH 접근 권한이 기본적으로 필요해요. 이 조건들이 충족되었다면 이제 본격적으로 설계에 들어갈 준비가 된 거예요.

실패 없는 컴포즈 서비스 자동화 설계 5단계

이제 본격적인 실행 단계로 넘어가 볼게요. 자동화는 단순히 명령어를 나열하는 게 아니라, 안전 장치를 겹겹이 쌓는 과정이라고 생각해야 해요. 각 단계를 꼼꼼하게 따라와 보세요.

STEP 1. 서비스 블록의 구조적 표준화

자동화를 시작하기 전, 가장 먼저 해야 할 일은 `docker-compose.yml` 파일을 표준화하는 거예요. 서비스 블록 내의 설정이 중구난방이면 자동화 스크립트가 어떤 파일을 읽어야 할지 혼란에 빠져요. 특히 환경 변수(Environment Variables) 관리가 핵심이에요.

모든 환경 변수는 별도의 `.env` 파일로 분리하고, 서비스 블록에서는 `${VARIABLE_NAME}` 형식을 사용하도록 통일하세요. 이렇게 하면 자동화 스크립트가 배포할 때마다 새로운 `.env` 파일을 생성하거나 교체하기가 매우 쉬워져요. 또한, 서비스 간의 의존 관계를 명확히 하기 위해 `depends_on` 설정을 반드시 포함해야 해요. 단순히 컨테이너가 뜨는 것뿐만 아니라, 데이터베이스가 준비될 때까지 기다리는 healthcheck 옵션을 함께 사용하는 것이 자동화의 첫 단추예요.

STEP 2. 배포용 쉘 스크립트 작성

CI/CD 도구를 쓰기 전, 서버 내부에서 실행할 수 있는 강력한 배포 스크립트(`deploy.sh`)를 만들어 두세요. 이 스크립트는 단순히 `up` 명령만 치는 게 아니라, 다음의 과정을 한 번에 처리해야 해요.

• 최신 이미지 풀링 (`docker-compose pull`)
• 기존 컨테이너 중지 및 삭제 (필요 시)
• 새로운 컨테이너 실행 (`docker-compose up -d`)
• 사용하지 않는 오래된 이미지 정리 (`docker image prune -f`)

예를 들어, 스크립트 안에 docker-compose up -d --remove-orphans를 넣으면, 설정 파일에서 삭제된 서비스까지 깔끔하게 정리해 줘서 서버가 지저분해지는 걸 막을 수 있어요. 이 스크립트가 완성되었다면, 여러분은 이미 수동 배포의 80%를 자동화한 셈이에요.

STEP 3. CI/CD 파이프라인 연동하기

이제 이 스크립트를 외부에서 자동으로 호출해 줄 차례예요. 요즘은 GitHub Actions를 사용하는 게 가장 대중적이고 효율적이에요. 개발자가 코드를 `main` 브랜치에 머지하면, GitHub 서버가 자동으로 빌드 작업을 수행하고 생성된 이미지를 레지스트리에 업로드한 뒤, 여러분의 서버에 SSH로 접속해 아까 만든 `deploy.sh`를 실행하게 만드는 구조예요.

파이프라인 설계 시에는 ‘빌드-푸시-배포’의 3단계 흐름을 유지하세요. 빌드 단계에서 테스트를 통과하지 못한 코드는 아예 배포 단계로 넘어가지 못하도록 차단하는 로직을 넣는 것이 매우 중요해요.

STEP 4. 배포 검증 및 헬스 체크 자동화

배포가 완료되었다고 해서 끝이 아니에요. 컨테이너는 떴지만, 내부 애플리케이션이 에러를 뿜으며 무한 재시작 중일 수도 있거든요. 그래서 배포 성공 여부를 확인하는 검증 단계를 반드시 파이프라인에 포함해야 해요.

가장 쉬운 방법은 스크립트 마지막에 `curl` 명령어를 넣어 특정 엔드포인트(예: `/health`)에 요청을 보내보는 거예요. 만약 200 OK 응답이 오지 않는다면 배포 실패로 간주하고 경고 알림을 보내도록 설정하세요. 조금 더 정교하게 하고 싶다면, 도커의 `inspect` 명령어를 사용해 컨테이너의 상태가 `running`인지, 그리고 `health` 상태가 `healthy`인지 확인하는 로직을 추가하는 것이 좋아요.

STEP 5. 안전한 롤백(Rollback) 시스템 구축

세상에 완벽한 배포는 없어요. 자동화의 완성은 실패했을 때 얼마나 빠르게 이전 상태로 돌아가는가에 달려 있어요. 롤백을 구현하는 가장 확실한 방법은 이미지 태그를 관리하는 거예요.

이미지 태그를 `latest`로만 관리하면 이전 버전이 무엇인지 알 수 없어 롤백이 불가능해요. 대신 Git의 커밋 해시(Commit Hash)나 버전 번호를 태그로 사용하세요. 이렇게 하면 문제가 발생했을 때 파이프라인이 즉시 이전 커밋 해시를 가진 이미지를 찾아 다시 `docker-compose up -d`를 실행하도록 설계할 수 있어요. 이것이 바로 진정한 의미의 ‘배포를 손에서 놓는 방법’입니다.

자주 하는 실수와 해결법 및 자주 묻는 질문

자동화를 구축하다 보면 예상치 못한 벽에 부딪히기 마련이에요. 실무에서 가장 흔히 발생하는 실수들을 정리했으니, 여러분의 상황과 비교해 보세요.

• ❌ 실수: 모든 이미지 태그를 ‘latest로만 사용함
  → 왜 발생하는가: 관리가 편해서 습관적으로 사용하게 됨
  → ✅ 해결법: Git 커밋 해시나 버전을 태그로 사용하여 명확한 이력을 남기세요.
• ❌ 실수: .env 파일의 민감 정보를 Git에 포함함
  → 왜 발생하는가: 로컬 환경 설정을 빠르게 공유하고 싶어서
  → ✅ 해결법: `.gitignore`에 반드시 추가하고, 운영 환경은 CI/CD Secret 기능을 활용하세요.
• ❌ 실수: 배포 스크립트에 오래된 이미지를 정리하는 로직 누락
  → 왜 발생하는가: 당장의 배포 성공에만 집중하기 때문
  → ✅ 해결법: `docker image prune -f` 명령어를 스크립트 마지막에 넣어 디스크 용량을 관리하세요.
• ❌ 실수: 네트워크 설정 미비로 서비스 간 통신 실패
  → 왜 발생하는가: 로컬에서는 잘 되던 것이 서버 환경에선 다르기 때문
  → ✅ 해결법: `networks` 섹션을 명시하여 서비스 간 통신 경로를 명확히 정의하세요.
• ❌ 실수: 컨테이너 실행 후 검증 단계 생략
  → 왜 발생하는가: 배포가 완료되면 끝이라고 착각하기 때문
  → ✅ 해결법: 헬스 체크 API를 호출하여 응답을 확인하는 단계를 반드시 포함하세요.

자주 묻는 질문

Q. 서비스가 하나만 업데이트되어야 하는데 전체를 다 다시 띄워야 하나요?

아니요, `docker-compose up -d [서비스명]` 명령어를 사용하면 특정 서비스만 변경 사항을 감지해서 다시 생성할 수 있어요. 다만, 환경 변수나 네트워크 설정이 바뀌었다면 전체적인 정합성을 위해 전체 재시작을 고려하는 것이 더 안전할 때가 많아요.

Q. DB 컨테이너는 자동화 배포에서 어떻게 관리하는 게 좋을까요?

데이터베이스는 상태를 가진(Stateful) 서비스이기 때문에 매우 조심스러워야 해요. DB 이미지 업데이트보다는 데이터 볼륨의 백업이 우선이에요. 배포 스크립트 실행 직전에 DB 스냅샷이나 백업 명령을 먼저 수행하도록 설계하는 것이 정석이에요.

Q. CI/CD 도구 없이 스크립트만으로도 충분할까요?

소규모 서버 하나라면 쉘 스크립트만으로도 충분히 훌륭한 자동화가 가능해요. 하지만 팀 단위로 협업하거나 배포 이력을 체계적으로 관리하고 싶다면 결국 GitHub Actions 같은 전문 도구가 필요해질 거예요.

Q. 롤백할 때 데이터 유실을 어떻게 막나요?
데이터 유실 방지의 핵심은 ‘데이터와 애플리케이션의 분리’예요. 모든 데이터는 컨테이너 내부가 아닌 외부 볼륨에 저장되어야 하며, 롤백 시에도 볼륨은 유지되도록 설정해야 해요.

자동화의 완성, 오늘부터 시작하는 단계별 로드맵

지금까지 컴포즈 services 자동화를 위한 설계부터 실행, 그리고 안정적인 운영 전략까지 모두 살펴보았어요. 자동화는 한 번에 완성되는 결과물이 아니라, 계속해서 다듬어 나가는 과정이에요. 처음에는 조금 복잡해 보여도, 한 번 구축해 두면 여러분의 소중한 시간을 지켜주는 가장 강력한 동료가 될 거예요.

막막하다면 다음의 로드맵을 따라 움직여 보세요.

• 오늘 할 일: 현재 사용 중인 `docker-compose up` 명령어들을 메모장에 순서대로 적어보기
• 이번 주 할 일: 자주 쓰는 명령어들을 모아 `deploy.sh`라는 파일로 만들기
• 실행 직전 할 일: GitHub Actions를 통해 서버에 SSH로 접속해 스크립트를 실행하는 테스트 해보기

가장 자주 반복하는 명령어 하나부터 스크립트로 옮겨 보세요. 작은 변화가 모여 여러분의 퇴근 시간을 앞당겨 줄 거예요. 배포의 두려움에서 벗어나 더 가치 있는 코드 작성에 집중하시길 응원합니다!

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