CI를 통해 안정적으로 Docker 이미지를 생성하여 GHCR에 저장했으니, 구동 환경에 접속해서 기존 컨테이너를 내리고 새로 올려야 한다.
사람이 직접 작업하면 항상 일관성(동일한 절차와 검증 과정)을 보장하기 어렵고, 반복 작업을 굳이 수동으로 할 필요가 없다면 노동도 자원인 만큼 효율적인 자동화를 고려해야 한다.

• 서버 구성
  • 운영 서버 단일 EC2 인스턴스
• Docker Image 태그 전략
  • 운영 서버 배포용(main): Semantic Version(MAJOR.MINOR.PATCH) (예시: v1.0.1)
  • 기능 개발 검증용(dev): dev-commit SHA, 최신 버전은 dev-latest
• 배포 단위
  • 프론트엔드, 백엔드, AI 각각 세 개의 Docker Image를 Docker Compose로 묶어 배포

서비스 중단 허용 여부

• 1차 배포에서는 부트캠프 내의 폐쇄 그룹에서 먼저 배포되고, 사용 시간이 일정하므로 서비스의 중단이 발생해도 괜찮다.
• 서비스 사용 시간대: 평일 쉬는 시간(9:00–18:00 중 매시 50분–정각) + 점심시간(12:00–13:00)

배포 전략

• In-Place: 새 버전 배포 시 컨테이너 재시작 동안 서비스 중단

배포 시간

• 정규 배포 시간: 매주 월요일 10시
• hotfix 배포 시간: main merge CI 단계가 끝난 뒤 곧바로 배포

• 환경별 배포 방법

  • product
    • 매주 월요일 오전 9시 Release Bundle 중 배포할 버전을 배포자가 직접 지정하여 실행
      => (09:00-09:50) AI, BE, FE가 개별 레포로 분리되어 있어 서비스 규격이 일치하며 검증된 버전 조합 최종 검토를 선행해야 한다.
      => (09:30) 사용자들에게 10:00부터 5분 미만(롤백 포함)의 다운타임이 발생할 수 있음을 충분히 고지했는지 확인해야 한다.
  • test
    • 별도 배포 자동화가 필요 없다.
    • Git SHA 태그와 latest 태그로 구성된 docker 이미지를 로컬에서 pull 받아 docker-compose.yml 파일을 활용하여 실행

• Release Bundle

  • 인프라 관리 레포에 즉시 배포 가능한 각 컨테이너 버전의 조합을 정의한 menifest 파일(releases/v0.0.0.yaml)을 저장한다.

  • 파일 생성 및 수정을 위해 워크플로우 각 레포의 배포할 버전 태그와 릴리즈 버전을 매개변수로 입력하면 GitHub Actions 러너가 자동 입력(휴먼 에러 방지)

  • 번들에 포함된 각 이미지가 GHCR에 실제로 존재하는지 Docker Registry API로 ping을 날려 확인 절차 필수

  • release/v1.1.0.yaml

      release_metadata:
        bundle_version: "v1.1.0"
        release_date: "2026-09-09T10:00:00+09:00"
        released_by: "janna"
        target_environment: "production"
        description: "정기 릴리즈 (채팅 안정화 및 AI 검증 API 최적화)"
      # 각 서비스별 컨테이너 이미지 및 Git 역추적 메타데이터
      services:
        backend:
          service_name: "springboot"
          image_uri: "ghcr.io/ktb-market/market-backend"
          image_tag: "v1.1.2"
          image_digest: "sha256:7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069"
          git_commit_sha: "a1b2c3d4e5f67890123456789abcdef012345678"
          git_commit_short: "a1b2c3d"
          git_ref: "refs/tags/v1.1.2"
          built_at: "2026-09-08T18:20:11Z"
          ci_workflow_run_id: "1782390123"
    
        ai:
          service_name: "fastapi"
          image_uri: "ghcr.io/ktb-market/market-ai"
          image_tag: "v1.1.0"
          image_digest: "sha256:3a4b5c6d7e8f90123456789abcdef0123456789abcdef0123456789abcdef01"
          git_commit_sha: "f9e8d7c6b5a43210fedcba9876543210fedcba98"
          git_commit_short: "f9e8d7c"
          git_ref: "refs/tags/v1.1.0"
          built_at: "2026-09-07T14:15:30Z"
          ci_workflow_run_id: "1771239981"

• workflow_dispatch

  • CD 워크플로우 실행 시 GHCR에 적재된 태그 중 배포할 Release Bundle의 RELEASE_VERSION을 매개변수로 수동 입력받아 배포한다.
  • 예시: RELEASE_VERSION=v1.0.0
    => [BACKEND_TAG:v1.0.2, AI_TAG:v1.0.1, FRONTEND_TAG:v1.0.0]를 포함한다.

• 승인 정책

  • Release Bundle 생성 시 BE, FE, AI 파트의 각 담당자를 포함하여 최소 3명 이상의 승인을 받아야 병합 가능하도록 설정
    => GitHub Environments의 워크플로우 승인자를 지정하는 설정은 일반 private 레포에서 사용할 수 없다.
    => Release Bundle은 검증을 끝낸 이미지 조합으로 간주하여 언제든 배포 가능한 상태이다.
    
  • 승인 기준: 선택된 버전, 직전 배포 대비 변경점, 멀티 레포 간 호환
• 운영 라이프사이클

  [1단계: 각 레포 main 병합]

  • FE, BE, AI 개별 레포에서 기능 완료 시 main에 병합 (주 3회)
  • CI가 돌며 GHCR에 고유 태그로 이미지 적재 (최근 5개 유지)

  [2단계: 정기 배포 준비 (월요일 08:30)]

  • 인프라 담당자가 create-release-manifest 워크플로우 실행
  • 자동으로 release/v1.1.0 브랜치 생성 및 PR 오픈

  [3단계: PR 리뷰 및 수정]

  • 팀원들(BE, FE, AI 리드)이 PR 코멘트 및 변경 내역 확인
  • [수정 발생 시]: 워크플로우 재실행으로 PR 브랜치 자동 갱신
  • 각 파트별 1명을 필수로 포함하여 3명 이상 승인 시 main에 병합

  [4단계: 실제 운영 배포 (월요일 10:00)]

  • CD 워크플로우 실행: RELEASE_VERSION="v1.1.0" 지정

  • 인프라 레포의 main에 머지된 releases/v1.1.0.yaml을 기반으로 EC2 순차 교체 배포 실행

In-Place: EC2 인스턴스에서 컨테이너 이미지 pull -> 기존 컨테이너 중지 및 제거 -> 새로운 컨테이너 실행
=> 변경 사항이 있는 컨테이너만 대상

docker compose pull <service>
docker compose up -d --no-deps <service>

• 무중단 배포 방식은 서버 리소스가 추가적으로 필요하고, 트래픽 라우팅 등 추가적인 아키텍처 구성이 필요하다.
• 1차 배포에서는 사용자가 30명으로 한정적이고, 사전에 대부분의 사용자에게 충분히 고지(디스코드)가 가능하기에 잠시 동안의 중단으로 인한 리스크는 무중단 배포에 필요한 리소스 대비 매우 적다.

1. Docker 엔진 레벨 Health Check(기동 여부 확인)
   • docker-compose.yml에 정의한 healthcheck 정책에 의해 수행
2. 애플리케이션 준비 상태 확인
   • Spring Boot Actuator 내부 엔드포인트를 호출하여 내부 의존성(DB) 정상 수립 검증
3. 외부 Nginx 라우팅 포트(443/80)를 통해 서비스 진입로 유효성 검증
   • 5XX Status Code 반환 시 실패

• 자동 롤백: 검증 실패(Timeout 등) 시 스크립트 레벨에서 수행
  1. Release Bundle의 문제가 발생한 버전 아래로 내림차순 정렬
  2. 정렬된 순서대로 최대 4번까지 버전을 하향하여 시도
     => 일주일에 최대 3개 버전이 생성될 것으로 예상되어 이전 주차의 안정된 배포 버전이 재시도 4회차에 도달하기 전에 적용
• 수동 롤백: CD 워크플로우 Release Bundle 버전을 하향 조정하여 실행

GitHub Secrets에 올인

• 서비스에 개인 정보 등 민감 정보가 포함되지 않아서 강력한 보안 수준이 요구되지 않는다.
• 상업적인 서비스가 아니라서 해커에게 위협을 받을 위험이 매우 적다.