[IT-방법] 도커 컴포즈 자동화와 CI/CD 연동 가이드 – 반복되는 배포 작업을 스크립트로 해결하는 법

수동 배포의 굴레에서 벗어나 자동화의 세계로

밤늦은 시간, 급하게 수정된 코드를 서버에 반영해야 하는 상황을 상상해 보세요. 터미널을 열고 익숙하게 docker-compose up -d 명령어를 입력하지만, 어딘가 불안한 마음이 가시지 않아요. 환경 변수 파일을 제대로 업데이트했는지, 예전 컨테이너의 잔재가 남아 네트워크 충돌을 일으키지는 않을지 걱정되곤 하죠. 이런 불안함은 결국 실수를 유발하고, 서비스 중단이라는 뼈아픈 결과로 이어지기도 해요.

매번 동일한 명령어를 입력하고, 로그를 확인하고, 컨테이너 상태를 점검하는 과정은 단순해 보이지만 매우 소모적이에요. 사람이 직접 개입하는 순간부터 오류의 가능성은 기하급수적으로 늘어나기 때문이죠. 이제는 도커 컴포즈 자동화를 통해 이런 반복적인 고통에서 벗어나야 할 때예요. 자동화는 단순히 편리함을 넘어, 서비스 운영의 안정성과 개발자의 정신 건강을 지켜주는 필수적인 방어 기제예요.

이 글에서는 단순히 명령어를 모아두는 수준을 넘어, 실무에서 바로 적용할 수 있는 체계적인 자동화 전략을 다뤄요. 배포 과정에서 발생할 수 있는 변수를 통제하고, 문제가 생겼을 때 즉시 이전 상태로 되돌리는 방법까지 상세히 설명해 드릴게요. 자동화 시스템을 구축하고 나면, 여러분은 배포 버튼 하나로 평온한 휴식을 즐길 수 있게 될 거예요.

이번 글에서 함께 살펴볼 핵심 내용은 다음과 같아요.

• 자동화가 필요한 대상과 준비 단계
• 쉘 스크립트부터 CI/CD 파이프라인까지의 설계 단계
• 배포 성공 여부를 확인하는 검증 프로세스
• 실패 상황에 대비한 안전한 롤백 전략

자동화를 시작하기 전 반드시 점검해야 할 사항들

자동화 시스템을 구축하기로 마음먹었다면, 무턱대고 스크립트부터 작성하는 것은 위험해요. 기초 공사가 부실하면 자동화 도구가 오히려 장애를 확산시키는 무기가 될 수 있기 때문이죠. 먼저 현재 여러분의 운영 환경이 얼마나 준비되어 있는지 객관적으로 파악해야 해요. 특히 컨테이너 간의 네트워크 구조와 데이터가 저장되는 볼륨의 관리 방식이 명확해야 자동화 과정에서 데이터 유실을 막을 수 있어요.

가장 먼저 확인해야 할 것은 환경 변수의 격리예요. 로컬 개발 환경과 운영 서버의 설정값은 반드시 달라야 하며, 이를 안전하게 주입할 수 있는 체계가 갖춰져 있어야 해요. 또한, 배포를 수행할 주체(사용자 또는 CI/CD 도구)가 서버에 접근할 수 있는 권한이 있는지, SSH 키나 API 토큰이 안전하게 관리되고 있는지도 필수 점검 대상이에요.

자동화의 수준을 결정하기 위해 아래 표를 통해 현재 상황을 비교해 보세요. 여러분의 팀에 가장 적합한 단계가 어디인지 판단하는 데 도움이 될 거예요.

선택 기준은 명확해요. 만약 혼자서 작은 프로젝트를 운영한다면 쉘 스크립트만으로도 충분한 효과를 볼 수 있어요. 하지만 여러 명의 개발자가 협업하거나 서비스의 규모가 커지고 있다면, 반드시 CI/CD 파이프라인을 도입하여 배포 이력을 남기고 권한을 중앙 집중화해야 해요.

준비가 끝났다면 이제 본격적으로 자동화의 설계도를 그려볼 차례예요. 단순한 명령어 나열이 아닌, 실패를 대비한 견고한 프로세스를 만드는 데 집중해야 해요.

단계별 도커 컴포즈 자동화 구축 프로세스

이제 본격적인 실행 단계로 들어갈게요. 자동화는 단순히 컨테이너 운영을 편하게 만드는 것을 넘어, 배포의 신뢰도를 높이는 과정이에요. 아래의 5가지 단계를 차근차근 따라오시면 실무에 적용 가능한 수준의 자동화 시스템을 갖출 수 있어요.

STEP 1. 환경 변수 관리와 보안 체계 구축

자동화의 첫 단추는 환경 변수를 어떻게 관리하느냐에 달려 있어요. 수동 배포 때는 직접 파일을 열어 수정할 수 있지만, 자동화 환경에서는 모든 설정값이 코드나 보안 저장소에서 유래해야 해요. 도커 컴포즈 자동화를 성공시키려면 `.env` 파일을 안전하게 주입하는 메커니즘을 먼저 만드세요.

가장 추천하는 방식은 CI/CD 도구(예: GitHub Actions)의 Secrets 기능을 활용하는 것이에요. DB 비밀번호나 API 키 같은 민감한 정보는 절대 코드 저장소에 올리지 마세요. 대신, 배포 스크립트가 실행될 때 해당 값을 읽어와서 실시간으로 `.env` 파일을 생성하거나, `docker compose –env-file` 옵션을 통해 직접 전달하는 방식을 사용해야 해요. 이렇게 하면 보안을 유지하면서도 환경에 맞는 유연한 배포가 가능해져요.

STEP 2. 쉘 스크립트를 활용한 기초 자동화 구현

CI/CD 도구를 도입하기 전, 먼저 배포 과정을 쉘 스크립트로 정형화하는 연습을 해보세요. `deploy.sh`라는 이름의 파일을 만들고, 반복되는 명령어를 순서대로 배치하는 거예요. 단순히 명령어만 적는 게 아니라, 각 단계의 성공 여부를 체크하는 로직을 넣는 것이 핵심이에요.

이상적인 배포 스크립트의 흐름은 다음과 같아요. 먼저 최신 코드를 가져오기 위해 `git pull`을 수행하고, 새로운 이미지를 빌드하거나 가져오기 위해 `docker compose pull`을 실행해요. 그 다음, docker compose up -d –remove-orphans 명령어를 사용하여 기존 컨테이너를 교체해요. 여기서 `–remove-orphans` 옵션은 매우 중요한데, 설정 파일에서 삭제된 서비스의 잔재를 깨끗하게 정리해 주기 때문이에요. 마지막으로 `docker image prune -f`를 실행하여 사용하지 않는 오래된 이미지를 삭제함으로써 서버 디스크 용량을 관리해 주는 센스도 필요해요.

STEP 3. CI/CD 파이프라인 설계와 적용

이제 쉘 스크립트를 더 큰 그림인 CI/CD 파이프라인에 통합할 단계예요. 가장 대중적인 GitHub Actions를 예로 들어볼게요. 파이프라인은 크게 빌드(Build) → 푸시(Push) → 배포(Deploy)의 3단계로 구성돼요.

코드 변경이 감지되면 서버에서 이미지를 빌드하고, 이를 Docker Hub나 AWS ECR 같은 컨테이너 레지스트리에 푸시해요. 그 다음, SSH를 통해 운영 서버에 접속하여 앞서 만든 `deploy.sh`를 실행하도록 명령을 내리는 방식이에요. 이 과정에서 배포 전용 계정을 별도로 만들어 권한을 최소화하는 것이 보안상 매우 중요해요. 자동화된 파이프라인이 구축되면, 개발자는 코드만 푸시할 뿐 서버에 접속할 필요조차 없어지게 돼요.

STEP 4. 블루-그린 배포 전략으로 중단 없는 서비스 운영

배포 중 서비스가 잠시라도 멈추는 것을 방지하고 싶다면 블루-그린(Blue-Green) 배포 방식을 고려해 보세요. 도커 컴포즈에서도 이 전략을 충분히 구현할 수 있어요. 핵심은 두 개의 서로 다른 프로젝트 이름을 사용하는 것이에요.

현재 서비스가 `project_blue`라는 이름으로 동작 중이라면, 새로운 버전은 `project_green`이라는 이름으로 별도의 네트워크와 컨테이너로 띄워요. 배포가 완료되고 신규 컨테이너가 정상적으로 작동하는 것을 확인한 뒤에, 로드 밸런서(Nginx 등)의 설정을 변경하여 트래픽을 `green` 쪽으로 돌려요. 만약 문제가 발생하면 즉시 트래픽을 다시 `blue`로 돌리면 되므로, 서비스 중단 시간을 거의 제로에 가깝게 유지할 수 있어요. 이는 운영 안정성을 극적으로 높여주는 고난도 기술이지만, 자동화와 결합했을 때 가장 강력한 힘을 발휘해요.

STEP 5. 배포 후 상태 검증 자동화

배포가 끝났다고 해서 모든 과정이 종료된 건 아니에요. 컨테이너는 떴지만 내부 애플리케이션이 에러를 내며 죽어있을 수도 있으니까요. 그래서 반드시 Health Check 단계를 자동화에 포함해야 해요.

도커 컴포즈 파일 내에 `healthcheck` 항목을 정의해 두면, 컨테이너가 단순히 ‘Running’ 상태인 것을 넘어 실제 서비스 요청을 처리할 준비가 되었는지 체크할 수 있어요. 자동화 스크립트에서는 `docker inspect` 명령어를 사용하여 컨테이너의 상태가 `healthy`로 변할 때까지 기다리는 로직을 추가하세요. 만약 일정 시간 내에 정상 상태가 되지 않는다면, 즉시 배포를 실패로 처리하고 알림을 보내도록 설계해야 해요. 이것이 바로 ‘진짜’ 자동화의 완성이에요.

자주 하는 실수와 해결법

자동화 시스템을 구축하다 보면 예상치 못한 벽에 부딪히기 마련이에요. 많은 개발자가 공통적으로 겪는 실수들을 정리했으니, 여러분의 상황과 비교해 보세요.

• ❌ –remove-orphans 옵션 누락 → 새로운 설정 파일에 없는 이전 서비스들이 서버에 계속 남아 네트워크와 자원을 낭비해요.
  ✅ 해결법: `docker compose up -d` 실행 시 반드시 `–remove-orphans` 플래그를 포함하세요.
• ❌ 환경 변수 보안 관리 실패
  `.env` 파일을 Git에 포함시켜 민감한 정보가 외부에 노출되는 사고가 발생해요.
  ✅ 해결법: `.gitignore`에 `.env`를 등록하고, CI/CD 도구의 비밀 저장소를 사용해 배포 시점에만 생성하세요.
• ❌ 볼륨 데이터 백업 미실시
  자동화 과정에서 컨테이너를 교체하다가 DB 볼륨 연결이 꼬여 데이터가 삭제될 수 있어요.
  ✅ 해결법: 배포 스크립트 최상단에 데이터베이스 백업 명령어를 넣어 물리적인 백업본을 먼저 확보하세요.
• ❌ 무조건적인 배포 진행
  애플리케이션이 에러로 인해 무한 재시작 중인데도 배포 성공으로 간주해요.
  ✅ 해결법: 반드시 `healthcheck` 결과를 확인하고, `healthy` 상태가 확인될 때까지 스크립트가 대기하도록 만드세요.
• ❌ 이미지 태그 고정(latest 사용)
  모든 이미지를 `latest` 태그로만 관리하면, 어떤 버전이 배포되었는지 추적하기 어렵고 롤백이 불가능해요.
  ✅ 해결법: Git Commit Hash나 버전 번호를 이미지 태그로 사용하여 고유성을 확보하세요.

자주 묻는 질문

Q. 자동화 스크립트가 실패하면 자동으로 이전 버전으로 돌아가나요?

기본적으로는 아니에요. 스크립트 내에 롤백 로직을 직접 작성해야 해요. 예를 들어, 배포 명령 실행 후 건강 상태 체크가 실패하면 `docker compose up -d <이전_태그>`를 실행하도록 조건문을 구성해야 해요.

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

규모가 아주 작다면 가능해요. 하지만 배포 이력을 확인하거나, 팀원들과 권한을 공유하고, 복잡한 파이프라인을 구성하기에는 한계가 명확해요. 성장을 고려한다면 CI/CD 도구를 병행하는 걸 추천해요.

Q. 서버 용량이 부족해지는 문제는 어떻게 해결하나요?
자동화 스크립트 마지막 단계에 `docker image prune -f`를 꼭 넣어주세요. 사용하지 않는 오래된 이미지들을 주기적으로 정리해 주는 것만으로도 큰 도움이 돼요.

Q. 도커 컴포즈 자동화가 서비스 중단을 유발할까 봐 무서워요.
그 불안함이 자동화를 만드는 원동력이에요. 블루-그린 배포나 롤백 전략을 도입하면, 수동 배포보다 훨씬 더 안전하게 운영할 수 있어요.

지속 가능한 운영을 위한 다음 단계

도커 컴포즈 자동화는 한 번 구축했다고 끝나는 것이 아니에요. 서비스가 성장함에 따라 더 복잡한 요구사항이 생길 것이고, 그때마다 자동화 시스템도 진화해야 해요. 오늘 배운 내용을 바탕으로 여러분의 운영 환경을 한 단계 업그레이드해 보세요.

이제 여러분이 해야 할 일은 아주 간단해요. 오늘 당장 가장 자주 반복하는 명령어 하나를 골라 작은 쉘 스크립트로 옮기는 것부터 시작해 보세요. 처음부터 거대한 파이프라인을 만들려고 욕심부리지 않아도 괜찮아요. 작은 성공이 쌓여 견고한 데브옵스 환경이 만들어지는 법이니까요.

이번 주에는 작성한 스크립트가 실패했을 때를 대비한 단순한 롤백 명령어를 테스트해 보는 것을 목표로 삼아보세요. 실행 직전에는 반드시 테스트 환경에서 충분히 검증하는 것도 잊지 마시고요!

더 깊이 있는 운영 지식이 궁금하다면 아래의 글을 함께 읽어보시는 것을 추천해요.

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