배포 프로세스 - prgrms-web-devcourse-final-project/WEB4_5_GAEPPADAK_BE GitHub Wiki

이 문서는 개발에 빠진 닭(team04-kkokkio) 팀의kkokkio 프로젝트의 배포 프로세스를 정리한 내용을 담고 있습니다. 현재 kkokkio 프로젝트는 CI/CD 자동화를 기반으로 GitHub Actions, Docker, EC2, RDS, Doppler를 사용하여 개발 환경에 안정적으로 배포합니다.

배포 구조

graph TD

    subgraph GitHub
        A1["PR 생성 (main 브랜치)"]
        A2["리뷰어 자동 할당"]
        A3["자동 테스트 실행"]
        A4{"테스트 성공 여부"}
        A5["PR 리뷰 및 머지"]
    end

    subgraph GitHub Actions 자동 배포
        B1["Tag 생성 및 GitHub Release"]
        B2["Docker 이미지 Build & Push"]
        B3["EC2 접속 후 이미지 Pull"]
        B4["기존 컨테이너 중지 및 최신 이미지 실행"]
    end

    subgraph 서비스 배포
        C1["EC2"]
        C2["RDS"]
        C3["Docker"]
        C4["Doppler"]
    end

    %% 메인 흐름
    A1 --> A2 --> A3 --> A4
    A4 -- 성공 --> A5 --> B1 --> B2 --> B3 --> B4

    %% 실패 루트
    A4 -- 실패 --> F1["코드 재작성"] --> A1

    %% 외부 시스템 연결
    B4 --> C1
    C1 --> C2
    C1 --> C3
    B4 --> C4
Loading

서비스 배포 아키텍처

graph TD
    subgraph EC2_인스턴스
        Backend["Docker: Backend App<br/>포트 8080"]
        Redis["Docker: Redis<br/>포트 6379"]
        Backend --> Redis
    end

    Doppler["Doppler<br/>(Secrets 관리)"]
    RDS["RDS (MySQL)<br/>VPC 내부"]

    Doppler --> Backend
    Backend --> RDS
Loading
  • EC2 인스턴스 내에서 백엔드와 Redis는 사용자 정의 Docker 네트워크(common)를 통해 통신
  • 백엔드에서 Doppler로부터 환경변수를 주입받고, RDS(MySQL)는 VPC 내부에서 연결

단계별 설명

단계 설명
1 개발 완료 후 main 브랜치로 Pull Request를 생성
2 자동 테스트가 실행되어 코드의 유효성을 검증
3 테스트가 통과하면 PR 리뷰 및 머지를 진행한다. 테스트 실패 시, 코드 수정 후 다시 PR을 등록
4 PR이 main 브랜치에 머지되면 GitHub Actions의 deploy-prd.yml 워크플로우가 실행됨. 해당 작업은 새로운 태그(v-prd-날짜)를 생성하고 GitHub Release를 발행
5 릴리즈 이후, 태그를 기반으로 Dockerfile.prd를 이용해 Docker 이미지를 빌드하며 GitHub Container Registry(GHCR)에 Push됨
6 이후 GitHub Actions가 AWS SSM(AWS Systems Manager)을 사용해 EC2 인스턴스에 접속하고, latest 태그의 이미지를 Pull한 후 기존 컨테이너를 중단함
7 새로 Pull한 이미지로 컨테이너를 실행하며, --restart always로 설정되어 시스템 재시작에도 자동 복구됨

자동 배포 조건

main 브랜치에서 다음 파일 변경 시 배포 워크플로우가 트리거 됨

  • backend/src/**,
  • build.gradle
  • Dockerfile.prd
  • .github/workflows/**

서비스 구성 요약

  • 백엔드 서버(Spring Boot)는 EC2 인스턴스에서 Docker 컨테이너로 실행
  • Redis는 같은 EC2 내에서 별도의 Docker 컨테이너로 실행되며, -network common 옵션으로 백엔드와 동일한 네트워크에서 연결
  • 데이터베이스는 AWS RDS(MySQL)이며, VPC 내부에서 EC2 인스턴스와 통신 가능하도록 보안 그룹 설정
  • 모든 민감한 환경 변수는 Doppler를 통해 주입되며, DOPPLER_TOKEN은 런타임 시 주입
  • DB 초기화 및 마이그레이션은 Flyway를 사용하여 애플리케이션 실행 시 자동 수행

실패 루트

  • 테스트 실패 시: 코드 재작성 → 다시 PR 루트로 회귀
  • 배포 실패 시, GitHub Actions 로그를 통해 원인 추적 후 동일한 태그로 수동 재배포 가능

사용 도구

  • CI/CD: GitHub Actions
  • 이미지 저장소: GitHub Container Registry (GHCR)
  • 서버: AWS EC2 (SSM 명령 기반 비SSH 접근)
  • 인프라 관리: Terraform
  • 환경 변수 관리: Doppler
  • DB 마이그레이션: Flyway
  • 캐시 서버: Redis (Docker 내부 실행)
  • 데이터베이스: AWS RDS (MySQL)

추가 정보

  • 자동 배포 시 EC2 인스턴스 접근은 SSM 기반으로 이뤄짐
  • Docker 이미지 버전 관리는 태그를 기준으로 진행됨
  • 배포 시 모든 로그는 GitHub Actions 콘솔에서 확인할 수 있음
⚠️ **GitHub.com Fallback** ⚠️