[Trouble_Shooting] CD 파이프라인 배포 실패 문제

[LeeCh0129]

📌 배운 내용

GitHub Actions를 통해 OCI 서버에 배포하는 CD(지속적 배포) 파이프라인이 실패하는 문제를 해결했습니다. 이 과정을 통해 Docker 명령어 버전 차이, Nginx와 Certbot의 상호 의존성으로 인한 교착 상태, 그리고 Certbot의 내부 캐시 문제 등 복합적인 원인을 체계적으로 진단하고 해결하는 방법을 남기고자 합니다.

• docker-compose (V1)와 docker compose (V2) 명령어의 차이점 및 호환성 확보 방법

• Nginx(SSL 인증서 필요)와 Certbot(Nginx 실행 필요)의 문제 해결

• 네트워크 문제 진단 시, 외부 요인(DNS, 클라우드 방화벽)과 내부 요인(OS 방화벽, 애플리케이션 설정)을 분리하여 테스트하는 방법의 중요성

• Certbot의 webroot 방식과 standalone 방식의 차이점 및 상황에 맞는 사용법

• "하드 리셋" (rm -rf ./certbot)을 통한 애플리케이션 캐시 문제 해결

🔍 배경 / 문제 상황

CI(build job)는 성공적으로 완료되었으나, develop 브랜치에 코드가 머지된 후 실행되는 CD(deploy job) 파이프라인이 OCI 서버에 배포하는 과정에서 계속 실패했습니다.

문제점:

• deploy job 로그에 docker-compose: command not found 에러가 발생했습니다.

• 해당 문제를 임시 조치한 후에도, docker compose ps 실행 시 Nginx 컨테이너가 Restarting 상태로 무한 재시작했습니다.

• 최종적으로 도메인 접속 시 ERR_CONNECTION_REFUSED 에러가 발생하여 서비스에 접근할 수 없었습니다.

목표:

• CD 파이프라인 실패의 근본 원인을 찾아 해결

• SSL 인증서를 성공적으로 발급받고, HTTPS 프로토콜로 사이트를 안정적으로 서비스

• 향후 유사한 문제가 발생하지 않도록 워크플로우를 안정화

✅ 핵심 정리 / 해결 방법

CD 파이프라인 실패는 Docker 명령어 비호환 문제와 Nginx-Certbot의 교착 상태 및 Certbot의 내부 캐시 문제가 복합적으로 작용한 결과였습니다.

체계적인 진단 과정을 통해 각 문제를 고립?시키고 순차적으로 해결하고자 했습니다. 특히, Nginx 설정을 극도로 단순화하여 네트워크 경로의 정상 작동을 먼저 증명한 뒤, Certbot의 인증 방식을 webroot에서 standalone으로 변경하고 캐시를 완전히 삭제하는 "하드 리셋"을 통해 SSL 인증서 발급에 최종적으로 성공했습니다.

🔥 트러블슈팅 상세 과정

1단계: docker-compose 명령어 비호환 문제

• 증상: deploy job 로그에 docker-compose: command not found 에러 발생.

• 원인 분석: 서버에는 최신 Docker와 함께 docker compose (공백, V2)가 설치되어 있었지만, 워크플로우 스크립트는 구버전인 docker-compose (하이픈, V1)를 사용하고 있었습니다.

• 해결:

  • 임시 조치: 서버에 sudo ln -s /usr/libexec/docker/cli-plugins/docker-compose /usr/local/bin/docker-compose 명령어로 심볼릭 링크를 생성하여, 구버전 명령어를 사용해도 최신 버전이 실행되도록 조치했습니다.

  • 근본 해결: deploy.yml 파일에서 모든 docker-compose를 docker compose로 수정했습니다.

2단계: Nginx 무한 재시작 문제 진단

• 증상: Nginx 컨테이너가 Restarting 상태로 표시되고, 도메인 접속 시 ERR_CONNECTION_REFUSED 발생.

• 원인 분석 및 해결 과정:

  1. 가설 1: DNS 문제? (폐기)
  • dnschecker.org와 GoDaddy 설정 페이지를 통해 globalnomad.site와 www 서브도메인 모두 정확한 IP로 전파되었음을 확인. DNS는 원인이 아님을 확인하였습니다.

2. 가설 2: Nginx 설정 또는 SSL 인증서 문제? (확인)

• docker compose logs nginx를 통해 [emerg] cannot load certificate... 오류를 확인. Nginx가 SSL 인증서 파일을 찾지 못해 시작에 실패하는 것을 발견했습니다.

이는 Certbot이 아직 인증서를 발급하지 못했기 때문이며, Nginx와 Certbot의 문제가 핵심임을 파악했습니다.

3. 네트워크 경로 최종 테스트 (문제 고립)

• 전략: 교착 상태를 풀기 위해, Nginx가 HTTPS 없이 80번 포트에서 간단한 테스트 파일만 서빙하도록 default.conf를 임시 수정했습니다.

• 실행: mkdir -p ./certbot/www/...로 디렉터리를 만들고 echo "test" > .../test.txt로 테스트 파일을 생성했습니다.

• 결과: PC 웹 브라우저에서 http://globalnomad.site/.well-known/acme-challenge/test.txt로 접속했을 때 Nginx test successful! 메시지를 확인. 이를 통해 OCI 보안 목록, 서버 iptables, Docker 네트워크 등 모든 외부 네트워크 경로는 완벽하게 정상임을 최종적으로 증명했습니다.

3단계: Certbot 인증 방식 변경 및 성공

• 증상: 네트워크 경로가 정상임에도 webroot 방식의 Certbot 인증이 계속 Connection refused 또는 No renewals were attempted로 실패했습니다.

• 원인 분석: Certbot 내부의 실패 기록 캐시 문제일 가능성이 높다고 판단했습니다.

• 해결:

  1. 방식 변경: Nginx를 완전히 끄고, Certbot이 직접 80번 포트를 사용하는 더 직접적인 standalone 방식으로 전환했습니다.

  2. 하드 리셋: standalone 방식도 실패 기록 캐시의 영향을 받을 수 있으므로, sudo rm -rf ./certbot 명령어로 모든 관련 디렉터리를 삭제하여 캐시를 완전히 초기화했습니다.

  3. 최종 성공: 깨끗한 상태에서 standalone 방식으로 Certbot을 실행하여 SSL 인증서를 성공적으로 발급받았습니다.

4.단계: 최종 배포 완료

발급받은 인증서를 사용하도록 nginx/conf.d/default.conf 파일을 원상복구했습니다.

docker compose up -d --force-recreate 옵션으로 모든 컨테이너를 강제 재시작하여 최종적으로 배포에 성공했습니다.