3단계: CD(지속적 배포) 파이프라인 구축

1. 개요

1.1. CD의 필요성

• Continuous Deployment는 코드가 준비되는 즉시 사람의 승인 없이 자동으로 운영 환경에 반영하여, 배포 속도를 최대화하고 배포 과정에서 발생하는 지연·수동 작업을 제거하기 위해서 사용.
• 개발 과정: 새로운 기능, 버그 수정을 개발 시 반영 내역을 확인하기 위해 테스트 서버 등에 배포 필요
• 운영 과정: 수동 배포 시 발생할 수 있는 실수 원천 방지, 소모 시간 및 비용 감소 위해 필요

1.2. 기대효과

• 수동 배포 대비 시간 대폭 감소 (15분 → 3~5분)
• 수동 배포 실수 원천 방지
• 롤백 자동화 기반 확보
• 작은 단위의 코드 변경을 자주 배포하여 빠른 기능 추가 가능

1.3. 요약

1. Artifacts: AWS S3 (Versioning: Commit SHA)
2. Agent: AWS CodeDeploy
3. Secrets: AWS Parameter Store
4. Notification: Discord Webhook
5. Environment Strategy:
   • Dev/Staging: Continuous Deployment (즉시 배포)
   • Prod: Continuous Delivery (수동 트리거)
6. Deployment Strategy: Blue/Green

2. 의사 결정

2.1. Artifact Repo

2.1.1. Artifact Repo 요구사항

• CI 빌드 산출물(jar, zip, static files 등)을 지칭
• 현재 컨테이너(Docker)를 도입하지 않은 단계이므로 Artifact Repo는 빌드 산출물 파일을 원본 그대로 저장할 수 있어야 함.
• 버전 관리: 배포 실패 시 즉시 롤백 할 수 있도록 아티팩트의 버전 식별이 가능해야 함.
• 우수한 접근성: CD 단계에서 보안 인증 및 통신이 원활하고 빠르게 진행되어야 함
• 유지보수 최소화: 별도의 서버를 구축하지않고 관리가 가능해야함.

2.1.2. 후보 기술

1. GitHub Actions (https://docs.github.com/ko/[email protected]/actions/tutorials/store-and-share-data)

• CI 워크플로우 실행 중에 생성되는 데이터를 같은 워크플로우 내의 다른 Job과 공유하거나, 실행 완료 후 다운로드할 수 있음
• 장점
  • 별도의 스토리지 및 서비스 구축 없이 GitHub Actions 스크립트로 구축 관리 가능
  • 무료 플랜 내 스토리지 사용 가능
• 단점
  • 보존 기간: 보관 기간 90일로 제한
  • 낮은 접근성: CD 과정에서 EC2 인스턴스에 전송하려면 GitHub API 토큰 인증을 통한 설정 필요
  • 용도 불일치: Build Job → Test Job의 데이터 전달, 로그 저장을 위해 설계된 기능.

⇒ CD를 위한 저장소로는 부적합

2. AWS S3

• AWS의 객체 스토리지 서비스
• 장점
  • 높은 접근성: AWS EC2에서 IAM Role 기반으로 인증 없이 접근 및 연동 가능. 추후 AWS Code Deploy 연동 사용시 편의성
  • 비용: AWS 예산 내에서 사용 가능하여 추가 비용 발생하지 않음
  • 유연성: Artifact 파일을 원본으로 저장 가능
  • 버전 관리: S3 버킷 버전 관리 / 계층형 구조 사용으로 롤백 시점 관리 가능
• 단점
  • 의존성 관리 등 추가 기능 부재

⇒ 현재 사용 구조 및 추후 AWS 인프라 내에서의 확장을 고려하여 가장 적절하다 판단.

3. Jfrog Artifatory

• 범용 artifact Repository 솔루션(파일, 패키지, 라이브러리, 컨테이너 이미지 등 관리 가능)
• 장점
  • 유연성: 다양한 언어와 패키지 매니저를 지원, 메타 데이터 관리 기능
  • 보안: Xray 기능을 통한 아티팩트 보안 취약점 스캔 가능
• 단점
  • 비용: SaaS 사용 시 추가 비용 발생. 무료 버전은 운영을 위한 Self-host 인프라 구축 필요
  • Over engineering: CI/CD 전반에 걸쳐 아티팩트 뿐만 아닌 다양한 내용에 대한 관리를 제공. 단순 Artifact Repo 로서 과도한 기능

⇒ 규모에 맞지 않는 과도한 서비스

4. Sonatype Nexus Repository Manager(https://help.sonatype.com/en/sonatype-nexus-repository.html)

• 소프트웨어 라이브러리, 의존성, 아티팩트 저장 관리 가능한 시스템(Java 생태계 중심)
• 장점
  • 기능: 다양한 배포 정책을 지원(Release, Snapshot, Mixed)하여 관리 용이
  • Proxy Repository: 외부 라이브러리 캐싱하여 빠른 빌드 가능
• 단점
  • 비용: 서비스 실행을 위한 인프라를 직접 구축해야함. (상용 Saas 솔루션은 유료 플랜)

⇒ 엔터프라이즈 중심 기능, 과도한 서비스

2.2. Versioning

2.2.1. 버저닝의 필요성

• 추적: 현재 배포되어 테스트/운영 중인 파일이 어떤 코드를 기반으로 한 것인지 식별
• 유일성: 버전간 이름을 구분하여 혼란 및 에러 방지
• 롤백: 장애 발생 시 어떤 버전으로 돌아갈 지 식별하기 위해서

2.2.2. 후보군

1. Commit SHA

• Git의 커밋 해시값을 그대로 버전 명으로 사용
• 장점
  • 완벽한 추적 가능
  • 자동화 용이: 배포 과정에서 별도 로직 없이 GitHub Actions 환경변수로 바로 접근 가능
• 단점
  • 순서 및 시점 파악 불가
  • 낮은 가독성

2. Semantic Versioning(SemVer)

• Major.Minor.Patch 형식의 전통적 버저닝 방법(예: 0.1.2 버전)
• 장점
  • 명확한 의미: 업데이트 중요도에 따른 버전 차이를 직관적으로 구분 가능
• 단점
  • 자동화 어려움: 매 배포마다 Major, Minor,Patch 중 어떤 버전 업인지에 따라 수동으로 구분지어주거나, 복잡한 스크립트 작성 필요

3. Timestamp

• 빌드된 날짜와 시간을 버전명으로 사용
• 장점
  • 정렬 최적화: 파일명으로 정렬 및 최근 버전 탐색이 가능
  • 직관성: 언제 배포된 파일인지 파악하기 쉬움
• 단점
  • 코드 추적 어려움: 어떤 코드를 기반으로 빌드했는지 알수 없음

4. 최종 결정: Hybrid 전략

• {YYYYMMDD_HHmmss}-{SHA}.{확장자} 구조로 작성
• 장점
  • 타임스탬프를 앞에 두어 정렬을 통해 최신 배포 파일을 즉시 식별 가능
  • 문제 발생 시 SHA 를 통해 코드 추적 가능
  • 자동화: 추가 로직 없이 단순 명령어로 생성 가능
  • 롤백: 타임스탬프, SHA 정보 기반으로 시간기준, 기능 배포 기준(코드 수정)으로 모두 롤백 가능

2.3. 서버 운영 전략

2.3.1. 서버 요구사항

• 개발 서버: 높은 성능 불필요(운영 서버와 같을 필요 없음), 상시 테스트 및 디버깅을 위해 상시 운영 필요
• 운영 서버: 높은 성능 필요. 서비스 상시 운영 필요
• 스테이징 서버: 운영 환경 검증을 위해 유사하거나 동일한 인프라 필요. 비용 절감을 위한 방안 필요

2.3.2. 스테이징 서버 운영 전략 비교

비용 추정은 t3.medium 서울리전 기준

1. 선택적 운영

• 운영 배포 직전, QA 필요시에만 수동으로 인스턴스를 시작하고, 검증 후 수동으로 중지하는 방식
• 장점
  • 비용 최적화: 테스트 수행 시간에만 운영
  • 단순함
• 단점
  • 자동화 단절: CI/CD 파이프라인은 서버가 켜진 상황을 전제로 동작. 완전 자동화 불가능
  • Cold Start: 서버 시작, 서비스 구동까지 대기 시간 발생

⇒ 극 초기 배포시, 스테이징 서버에서 테스트가 거의 없는 경우 선택 가능. 정기 배포, 수시 배포 사이클이 완성되면 완전 자동화로 전환 가능

2. On-Demand(상시 운영)

• 운영 서버와 비슷한 구조로 즉시 테스트 가능하나, 많은 비용 발생
• 비용 추정: 약 $37

3. On-Demand + Scheduler(Time-based)

• 업무시간, 배포 이전 시간에만 켜두고, 이 외 시간은 자동으로 끄는 방식
• 사용 시간만큼 과금으로 비용 절약 가능.
• 다양한 배포가 진행되는 초기 개발 단계에 대응하기 어려움
• 밤, 주말 시간 배포 필요 시 수동 작동 필요
• 비용 추정: 약 $11(온디멘드 대비 약 70% 절감)

4. Spot Instance

• AWS 스팟 인스턴스를 사용하여 비슷한 인프라를 저가에 켜두는 방식
• 상시 운영으로 즉시 테스트 가능
• AWS 회수 시 꺼질 수 있음. 상태 유지(EBS 설정) 필요(Interruption Behavior 수정, 기존 Terminate(삭제) → Stop(중지) 로 변경하면 EBS 유지 상태로 재시작 가능)
• ASG와 연동하여 자동 복구 가능(Spot Instance로 구성된 ASG 생성)
• 비용 추정: 약 $11(온디벤드 대비 약 70% 절감)

5. 임시 환경 구축

• Dev → Release PR 생성을 트리거로 임시 서버를 생성 후 배포.
• 완벽한 격리 환경에서 테스트 가능 및 비용 극단적 절약
• 복잡한 구축 방식(IaC)필요.(오버엔지니어링)

최종 결정: Spot Instance 사용하여 스테이징 서버 구축

환경	운영 방식	장점	단점
개발 (Dev)	상시 가동, 즉시 배포	- 개발 생산성 최적화 (기다림 없음). - 언제든 접속해 로그 확인 가능.	- 상시 운영으로 인한 비용 발생.
스테이징 (Staging)	AWS Spot Instance 사용	- 비용 절감 효과 확실. - 빠른 스테이징 테스트 가능	중단 가능성 있음
운영 (Prod)	상시 가동, 수동 승인	- 안정성 확보. - 사용자 서비스 보장.

2.4. Rollback 전략

1. 개발 서버: 수동 롤백

• 디버깅 환경 보존을 위해 상태를 유지 할 필요가 있음
• 개발 단계에서는 이전 버전으로 롤백 후 다시 확인하는 것 보다 버그 수정 후 커밋하여 재 배포하고 확인하는것이 효율적

2. 스테이징 서버: Hybrid

• 배포 실패 시 자동 롤백
  • 운영과 동일한 배포 / 롤백 스크립트의 작동을 확인해야 함
  • 테스트(QA)를 위한 서버 작동 필요
• 기능 결함 시 수동 롤백
  • 배포에는 문제 없으나, 기능에 문제가 있는 경우 테스트 및 개발자 확인 후 수동 롤백 및 핫픽스 배포

3. 운영서버: 자동 롤백(+ 수동 트리거)

• 문제 발생 시 서버 다운타임 최소화 위해 직전 배포로 자동 롤백
• 숨은 로직 에러 발생시 대응을 위한 수동 트리거는 필요

2.5. 환경별 CD 운영 전략

환경	대상 브랜치	트리거(Trigger) 조건	배포 전략	설명
Dev (개발)	dev	자동 트리거(PR Merge 시)	단순 재시작	- 속도 우선 - 개발자가 코드를 올리자마자 서버에 반영되어 기능 확인 가능 - 다운타임 허용
Staging (검증)	release	자동 트리거(PR Merge 시)	Blue/Green (무중단 배포)	- 검증 우선 - 운영 배포 전, 실제 데이터와 유사한 환경에서 QA 진행 - 운영환경과 동일한 설정 검증
Prod (운영)	main	수동 승인 (Manual)	Blue/Green(무중단 배포)	- 안정성 우선 - main에 머지되어도 즉시 배포하지 않음 - 관리자가 GitHub Actions에서 승인하여 수동 트리거 - 사용자 경험을 위해 무중단 배포

2.6. 배포 에이전트 선택

방식	설명	장점 (Pros)	단점 (Cons)	우리 서비스 적합성
SSH Script (via GitHub Actions)	GitHub Runner가 EC2에 SSH로 접속하여 쉘 스크립트 실행	- 구축 속도: appleboy/ssh-action 사용하여 빠른 설정 가능 - 유연성: 리눅스 명령어 그대로 사용 가능.	- 보안: GitHub Secrets에 PEM 키를 저장해야 함, ssh 포트 전체 개방 필요 - IP 제한: 보안그룹(SG)에서 GitHub IP 대역을 열거나 Bastion을 거쳐야 함. - 확장성: 추후 오토스케일링 적용 시 자동 배포 불가	- 단일 인스턴스 환경에서 가장 빠르고 직관적 - 추후 ASG 설정 시 AWS CodeDeploy로 마이그레이션 필수.(기술부채 발생)
AWS CodeDeploy	AWS의 공식 배포 관리 서비스 사용 (Agent 설치 필요)	- 안정성: 배포 실패 시 자동 롤백 기능 내장. - 확장성: 추후 Auto Scaling Group 적용 시 자동 배포 지원. - 무료: EC2 배포 시 추가 비용 없음. - 보안: Inbound 포트 오픈 불필요	- 러닝 커브: IAM Role, AppSpec.yml 등 초기 설정 복잡. - 종속성: AWS 전용 설정 파일 관리 필요.	- 다중 인스턴스(ASG) 단계로 넘어가면 도입 필수 - 기술부채 방지 및 보안성, 안정성 우수.
Self-hosted Runner	EC2 내부에 GitHub Runner 설치하여 실행	- 보안 최상: 외부에서 들어오는 SSH 포트(22)를 열 필요 없음 (Outbound 통신).	- 리소스 소모: Runner 프로세스가 서버 CPU/RAM을 점유함 (단일 인스턴스에 치명적). - 관리 비용: Runner 업데이트 및 좀비 프로세스 관리 필요.	단일 인스턴스 환경인 V1에서는 불가. 서버 자원이 추가 필요하여 부적절하다고 판단.

2.7. 환경변수 주입

1. GitHub Secret
   • 배포 시점에 GitHub가 .env 파일을 만들어 서버에 전송
   • 장점: 깃허브 레포지토리에서 바로 설정할 수 있음
   • 단점: 보안문제(Secret 값이 서버 디스크에 남음)
2. AWS Parameter Store
   • 배포 후 서버 부팅 시점에 AWS API 호출하여 값 가져오기
   • 장점: 보안(값을 메모리에만 저장하거나, 암호화 관리 가능), 이력 관리 및 계층형 관리 가능
   • 단점: 복잡한 설정(SDK 연동 코드 작성 필요)

2.8. 알림 채널

1. Discord(선정)
   • 현재 팀 내부에서 사용중인 메신저.
   • 장점: 비용 무료, 단순한 연동(Webhook)
   • 단점: 개발 도구에 최적화 되지 않은 플랫폼
2. Slack
   • 메신저 기반 협업 툴
   • 장점: 다양한 개발도구와 연동을 지원하는 라이브러리
   • 단점: 추가 비용 발생(무료 플랜 사용시 90일 이후 메시지 삭제→ 배포 등 이력 추적 불가)

2.9. 배포 범위 및 방식

• Dev(개발), Staging 서버

  • 개발 및 검증 과정은 하루에 수 회 발생
  • 빠른 MVP 개발과정을 보조하기 위해 빠른 배포 필요
  • 버그가 있어도 확인 후 수정하면 되므로 승인 절차 불요

  ⇒ Continous Deployment(완전 자동 배포) 선정

• Production(운영)

  • 운영 배포는 낮은 빈도로 발생
  • 운영의 안정성이 최우선
  • 휴먼에러(잘못된 코드 머지, 수정 등)가 발생해도 배포 전 한번 더 확인 할 수 있는 안전장치 확보 필요

  ⇒Continuous Delivery(승인 후 배포) 선정

2.10. 배포 전략

• 서비스 특성(취업 일정 관리, AI 피드백)상 데이터 무결성과 사용자 경험(끊김 없음) 중요
• 서비스 중단 시 발생할 수 있는 문제
  • 일정 관리 서비스에서 알림 먹통 발생 가능성
  • 일정 생성, 커뮤니티 글 작성 도중 연결 끊김으로 데이터 유실
  • AI 이력서 피드백 응답 중 (Long-polling) 요청 끊김
• 따라서 무중단 배포를 요구

무중단 배포 전략 비교

• 롤링 업데이트

  • 일부 서버를 끄고 새 버전을 실행하여 점진적으로 교체하는 방식. 단일 인스턴스의 경우 다운타임이 무조건 발생.
  • 장점: 추가 리소스 불요
  • 단점: 서비스 중단 발생

  ⇒ 무중단 필요하므로 배제

• 블루/그린

  • 동일한 인프라를 하나 더 띄우는 방식
  • 장점: 문제 발생 시 즉시 롤백 가능, 무중단 배포 가능
  • 단점: 일시적으로 인프라 2배 필요

  ⇒ 가장 간단하게 무중단을 구현할 수 있음

• 카나리

  • 트래픽의 일부만 새 버전으로 보내, 점진적 전환하는 방식
  • 장점: 서버 문제 발생 시 리스크 최소화 가능, 성능 테스트에 유용
  • 단점: 라우팅 설정의 복잡성, 트래픽 분산 장비 필요, 트래픽 전환 동안 인프라 2배 필요

  ⇒ 많지 않은 트래픽 중 일부를 대상으로 분석해야하므로, 트래픽이 적은 현 시점에서는 효율성이 떨어져 배제 (10%를 우선 보내는 상황 가정 시 V1 트래픽 피크 100명 기준 10명 만 새 버전으로 전환)

• 셰도우 배포

  • 트래픽 일부를 새 버전에 전달하며, 응답은 사용자에게 반환하지 않는 방식
  • 카나리 전략과의 차이점
    • 카나리는 일부 트래픽을 대상으로 테스트를 시도. 셰도우는 전체 트래픽 대상
    • 카나리는 새 버전 문제 발생 시 일부 트래픽이 영향 받음. 셰도우는 영향 없음.
  • 장점: 실제 트래픽을 통한 검증 가능, 사용자 경험 무손실, 새 버전 대상 실시간 피드백 가능, 새 버전 문제 발생시에도 서비스 영향 없음
  • 단점: 트래픽 설정 복잡성, 인프라 두배 필요, Shadow 트래픽 응답 분석을 위한 추가 도구 필요, 트래픽 전환 동안 인프라 2배 필요

  ⇒ 극단적으로 높은 신뢰성을 요구하는 경우 적절하겠으나, 즉시 롤백 가능하므로 최우선 고려하지 않음.

⇒ 블루/그린 배포 선정

3. 배포 파이프라인 상세 설계

이전 단계의 의사결정을 바탕으로 CD 과정을 구체적으로 설계.

3.1. 전체 파이프라인 흐름도

• CI 완료(S3) → 브랜치 분기 → 환경별(Dev/Staging/Prod) 배포 프로세스 다이어그램

3.2. 서버 내부 배포/롤백 흐름도 (Micro View)

• CodeDeploy Agent 동작 → 포트 확인 → Blue/Green 스위칭 → 헬스 체크 → 롤백/성공 판정 메커니즘

3.2.1. 개발서버

배포 방식 요약

• In Place 배포(링크)

1. Stop: 돌고 있던, 구버전 프로세스 및 서버를 종료(다운타임 허용)

2. Update: Artifact Repo인 S3에서 최신 파일을 받아와 덮어쓰기

3. Start: 새 버전을 받아와 실행

4. 검증: 새 버전의 정상 실행 여부를 검사

   4.1. 정상 실행: 배포 완료 알림 및 후속 작업

   4.2. 오류 발생: 실패 알림 및 환경 보존

5. 롤백: 디버깅 후 수동 트리거 이후 이전 버전으로 롤백 및 새 버전으로 신규 배포

필수 설정 사항

• EC2 설정

  • 인스턴스 설정: t3.medium

  • 스왑 메모리 설정: 4GB

  • 서버 초기 설정 스크립트 (각종 의존성 버전은 스택에 맞게 확정 후 수정 예정)

    #!/bin/bash
    # 1. 시스템 업데이트 및 필수 패키지 설치
    sudo apt-get update -y
    sudo apt-get install -y ruby wget curl git jq awscli
    
    # 2. Swap 메모리 4GB 설정
    sudo fallocate -l 4G /swapfile
    sudo chmod 600 /swapfile
    sudo mkswap /swapfile
    sudo swapon /swapfile
    echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
    
    # 3. CodeDeploy Agent 설치
    cd /home/ubuntu
    wget https://aws-codedeploy-ap-northeast-2.s3.ap-northeast-2.amazonaws.com/latest/install
    chmod +x ./install
    sudo ./install auto
    
    # 4. Runtimes 설치
    # 4-1. Java 21
    wget -O - https://packages.adoptium.net/artifactory/api/gpg/key/public | sudo apt-key add -
    echo "deb https://packages.adoptium.net/artifactory/deb $(awk -F= '/^VERSION_CODENAME/{print$2}' /etc/os-release) main" | sudo tee /etc/apt/sources.list.d/adoptium.list
    sudo apt-get update
    sudo apt-get install -y temurin-21-jdk
    
    # 4-2. Node.js 20 & PM2
    curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
    sudo apt-get install -y nodejs
    sudo npm install -g pm2
    
    # 4-3. Python 3.10 & venv
    sudo apt-get install -y python3.10 python3.10-venv python3-pip
    
    # 5. 디렉토리 구조 생성 및 권한 설정
    mkdir -p /home/ubuntu/apps/{backend,frontend,ai}
    sudo chown -R ubuntu:ubuntu /home/ubuntu/apps
    

• AWS CodeDeploy 배포 그룹 설정

  • 배포 유형: In-Place 배포
  • 배포 구성: CodeDeployDefault.AllAtOnce (한 번에 배포)
  • IAM Role 설정: Parameter Store를 통한 환경변수 주입을 위해 AmazonSSMReadOnlyAccess 권한 설정
  • 로드밸런서: 설정 해제
  • 롤백 구성: 해제

• 서비스 별 설정 및 스크립트

  • BE(Spring Boot)

    • 경로: /home/ubuntu/apps/backend

    • 포트: 8080

    • appspec.yml

      version: 0.0
      os: linux
      files:
        - source: /
          destination: /home/ubuntu/apps/backend
          overwrite: true
      
      permissions:
        - object: /home/ubuntu/apps/backend/scripts
          pattern: "**"
          owner: ubuntu
          group: ubuntu
          mode: 755
      
      hooks:
        ApplicationStop:
          - location: scripts/stop.sh
            timeout: 60
            runas: ubuntu
        ApplicationStart:
          - location: scripts/start.sh
            timeout: 60
            runas: ubuntu
        ValidateService:
          - location: scripts/validate.sh
            timeout: 60
            runas: ubuntu
      

    • stop.sh

      #!/bin/bash
      # 실행 중인 JAR 프로세스 찾기
      PID=$(pgrep -f 'backend.jar')
      
      if [ -z "$PID" ]; then
        echo ">>> 구동 중인 백엔드 애플리케이션이 없습니다."
      else
        echo ">>> 프로세스 종료 시도 (PID: $PID)"
        kill -15 $PID # Graceful Shutdown
        sleep 5
      fi
      

    • start.sh

      #!/bin/bash
      PROJECT_ROOT="/home/ubuntu/apps/backend"
      DISCORD_SCRIPT="$PROJECT_ROOT/scripts/utils/discord.sh"
      
      cd $PROJECT_ROOT
      
      # [에러 핸들러] 스크립트 실행 중 에러 발생(ERR) 시 실행됨
      error_handler() {
        echo ">>> [Error] 스크립트 실행 실패"
        bash $DISCORD_SCRIPT "배포 실패 (Backend)" "ApplicationStart 단계에서 에러가 발생했습니다.\n로그를 확인해주세요." "fail"
      }
      # 에러(ERR) 시그널을 받으면 error_handler 함수 실행
      trap 'error_handler' ERR
      
      # --------------------------------------------------------
      
      # 시작 알림 전송
      echo ">>> [Start] 백엔드 배포 시작"
      bash $DISCORD_SCRIPT "배포 시작 (Backend)" "Spring Boot 애플리케이션 구동을 시작합니다." "info"
      
      # 앱 실행
      nohup java -jar backend.jar > app.log 2>&1 &
      
      # nohup은 성공해도 바로 리턴. 프로세스가 진짜 떴는지 1초 뒤 확인
      sleep 2
      PID=$(pgrep -f 'backend.jar')
      
      if [ -z "$PID" ]; then
        echo ">>> 프로세스가 실행되지 않았습니다."
        exit 1 # 여기서 에러가 나면 위 trap이 발동해서 디스코드 알림
      fi
      
      echo ">>> [Start] 프로세스 실행 확인됨 (PID: $PID)"
      

    • validate.sh

      #!/bin/bash
      PROJECT_ROOT="/home/ubuntu/apps/backend"
      DISCORD_SCRIPT="$PROJECT_ROOT/scripts/utils/discord.sh"
      
      # [에러 핸들러]
      error_handler() {
        bash $DISCORD_SCRIPT "헬스 체크 실패 (Backend)" "서버가 정상적으로 응답하지 않습니다 (Timeout/500).\n확인이 필요합니다." "fail"
      }
      trap 'error_handler' ERR
      
      # --------------------------------------------------------
      
      echo ">>> [Validate] Health Check 시작"
      
      for i in {1..10}; do
        response=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/health)
        
        if [ "$response" == "200" ]; then
          echo ">>> Health Check 성공 (200 OK)"
          
          # 최종 성공 알림
          bash $DISCORD_SCRIPT "배포 완료 (Backend)" "헬스 체크 통과. 정상 서비스 중입니다." "success"
          exit 0
        fi
        
        bash $DISCORD_SCRIPT "구동 대기중... ($i/10)" "응답 코드: $response" "info"
        sleep 10
      done
      
      # 반복문이 끝날 때까지 200이 안 나오면 에러 처리
      echo ">>> Health Check 최종 실패"
      exit 1 # -> trap 발동 -> 실패 알림 전송
      

  • FE(Next.js)

    • 경로: /home/ubuntu/apps/frontend

    • 포트: 3000

    • appspec.yml

      version: 0.0
      os: linux
      files:
        - source: /
          destination: /home/ubuntu/apps/frontend
          overwrite: true
      
      permissions:
        - object: /home/ubuntu/apps/frontend/scripts
          pattern: "**"
          owner: ubuntu
          group: ubuntu
          mode: 755
      
      hooks:
        ApplicationStop:
          - location: scripts/stop.sh
            timeout: 60
            runas: ubuntu
        AfterInstall:
          - location: scripts/install_dependencies.sh
            timeout: 300
            runas: ubuntu
        ApplicationStart:
          - location: scripts/start.sh
            timeout: 60
            runas: ubuntu
        ValidateService:
          - location: scripts/validate.sh
            timeout: 60
            runas: ubuntu
      

    • stop.sh

      #!/bin/bash
      echo ">>> [Stop] Frontend 프로세스 종료"
      pm2 delete frontend || true
      

    • install_dependencies.sh

      💡NEXT_PUBLIC_ 환경변수는 실행 단계에서 주입할 수 없으며, 반영되지 않음. 빌드가 진행되는 CI에서 주입 필요!

      #!/bin/bash
      PROJECT_ROOT="/home/ubuntu/apps/frontend"
      DISCORD_SCRIPT="$PROJECT_ROOT/scripts/utils/discord.sh"
      
      cd $PROJECT_ROOT
      
      # [에러 핸들러]
      error_handler() {
        echo ">>> [Error] 의존성 설치 실패"
        bash $DISCORD_SCRIPT "배포 실패 (Frontend)" "AfterInstall(npm ci) 단계에서 에러가 발생했습니다." "fail"
      }
      trap 'error_handler' ERR
      
      # --------------------------------------------------------
      
      echo ">>> [Install] Production 의존성 설치"
      # CI에서 node_modules를 가져오지 않았으므로 여기서 설치
      npm ci --only=production
      

    • start.sh

      #!/bin/bash
      PROJECT_ROOT="/home/ubuntu/apps/frontend"
      DISCORD_SCRIPT="$PROJECT_ROOT/scripts/utils/discord.sh"
      
      cd $PROJECT_ROOT
      
      # [에러 핸들러]
      error_handler() {
        echo ">>> [Error] PM2 실행 실패"
        bash $DISCORD_SCRIPT "배포 실패 (Frontend)" "ApplicationStart(PM2) 단계에서 에러가 발생했습니다." "fail"
      }
      trap 'error_handler' ERR
      
      # --------------------------------------------------------
      
      # 시작 알림
      bash $DISCORD_SCRIPT "배포 시작 (Frontend)" "Next.js 애플리케이션(PM2) 구동을 시작합니다." "info"
      
      echo ">>> [Start] Frontend(PM2) 실행"
      # 기존 로그 비우기
      pm2 flush frontend || true
      
      # PM2 시작 (이미 떠있으면 리스타트, 없으면 시작)
      # 환경변수는 빌드 타임 주입 or 런타임 코드 레벨 처리 가정
      pm2 start npm --name "frontend" -- start
      

    • validate.sh

      #!/bin/bash
      PROJECT_ROOT="/home/ubuntu/apps/frontend"
      DISCORD_SCRIPT="$PROJECT_ROOT/scripts/utils/discord.sh"
      
      # [에러 핸들러]
      error_handler() {
        bash $DISCORD_SCRIPT "헬스 체크 실패 (Frontend)" "서버가 정상적으로 응답하지 않습니다 (Timeout/500)." "fail"
      }
      trap 'error_handler' ERR
      
      # --------------------------------------------------------
      
      echo ">>> [Validate] Frontend 구동 확인"
      
      for i in {1..10}; do
        # Next.js 메인 페이지(3000포트) 확인
        response=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:3000)
        
        if [ "$response" == "200" ]; then
          echo ">>> Frontend 정상 동작 확인"
          
          # 최종 성공 알림
          bash $DISCORD_SCRIPT "배포 완료 (Frontend)" "헬스 체크 통과! 정상 서비스 중입니다." "success"
          exit 0
        fi
        
        bash $DISCORD_SCRIPT "구동 대기중... ($i/10)" "응답 코드: $response" "info"
        sleep 5
      done
      
      echo ">>> Frontend 구동 실패"
      exit 1 # -> trap 발동
      

  • AI(FastAPI)

    • 경로: /home/ubuntu/apps/ai

    • 포트: 8000

    • appspec.yml

      version: 0.0
      os: linux
      files:
        - source: /
          destination: /home/ubuntu/apps/ai
          overwrite: true
      
      permissions:
        - object: /home/ubuntu/apps/ai/scripts
          pattern: "**"
          owner: ubuntu
          group: ubuntu
          mode: 755
      
      hooks:
        ApplicationStop:
          - location: scripts/stop.sh
            timeout: 60
            runas: ubuntu
        AfterInstall:
          - location: scripts/setup_env.sh
            timeout: 60
            runas: ubuntu
        ApplicationStart:
          - location: scripts/start.sh
            timeout: 180 # AI 라이브러리 로딩 시간 고려
            runas: ubuntu
      

    • stop.sh

      #!/bin/bash
      PID=$(pgrep -f 'uvicorn main:app')
      
      if [ -z "$PID" ]; then
        echo ">>> 구동 중인 AI 애플리케이션이 없습니다."
      else
        kill -15 $PID
        sleep 3
      fi
      

    • start.sh

      #!/bin/bash
      PROJECT_ROOT="/home/ubuntu/apps/ai"
      VENV_PATH="$PROJECT_ROOT/venv"
      DISCORD_SCRIPT="$PROJECT_ROOT/scripts/utils/discord.sh"
      
      cd $PROJECT_ROOT
      
      # [에러 핸들러]
      error_handler() {
        echo ">>> [Error] AI 서버 실행 실패"
        bash $DISCORD_SCRIPT "배포 실패 (AI)" "ApplicationStart(Pip/Uvicorn) 단계에서 에러가 발생했습니다.\n로그를 확인해주세요." "fail"
      }
      trap 'error_handler' ERR
      
      # --------------------------------------------------------
      
      # 시작 알림
      bash $DISCORD_SCRIPT "배포 시작 (AI)" "FastAPI 가상환경 설정 및 구동을 시작합니다." "info"
      
      echo ">>> [Start] 가상환경 설정 및 패키지 설치"
      if [ ! -d "$VENV_PATH" ]; then
          echo ">>> 가상환경 생성 중..."
          python3 -m venv $VENV_PATH
      fi
      
      # 가상환경 활성화
      source $VENV_PATH/bin/activate
      
      # 의존성 설치
      pip install -r requirements.txt
      
      echo ">>> [Start] Uvicorn 서버 실행"
      # 환경변수는 Python 코드(boto3) 내부에서 로드됨
      nohup uvicorn main:app --host 0.0.0.0 --port 8000 > app.log 2>&1 &
      
      # 프로세스 생성 확인
      sleep 2
      PID=$(pgrep -f 'uvicorn main:app')
      
      if [ -z "$PID" ]; then
        echo ">>> 프로세스가 실행되지 않았습니다."
        exit 1 # trap 발동
      fi
      
      echo ">>> PID: $PID 실행 확인됨"
      

    • validate.sh

      #!/bin/bash
      PROJECT_ROOT="/home/ubuntu/apps/ai"
      DISCORD_SCRIPT="$PROJECT_ROOT/scripts/utils/discord.sh"
      
      # [에러 핸들러]
      error_handler() {
        bash $DISCORD_SCRIPT "헬스 체크 실패 (AI)" "AI 서버가 응답하지 않습니다. (/health 엔드포인트 확인 필요)" "fail"
      }
      trap 'error_handler' ERR
      
      # --------------------------------------------------------
      
      echo ">>> [Validate] AI Server Health Check"
      
      for i in {1..10}; do
        response=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/health)
        
        if [ "$response" == "200" ]; then
          echo ">>> AI Server 정상 동작 확인"
          
          # 최종 성공 알림
          bash $DISCORD_SCRIPT "배포 완료 (AI)" "헬스 체크 통과! 모델 서빙 준비 완료." "success"
          exit 0
        fi
        
        bash $DISCORD_SCRIPT "AI 구동 대기중... ($i/10)" "응답 코드: $response" "info"
        sleep 5
      done
      
      echo ">>> AI Server 구동 실패"
      exit 1 # -> trap 발동
      

3.2.2. 스테이징 서버

배포방식 요약

• Blue/Green 배포
  • 단일 인스턴스 환경에서 Blue/Green 구현하기 위해 Port 스위칭 사용
• Spot Instance 사용으로 비용 절감
  • AWS ASG를 사용하여 Spot Instance 중단 시 자동 복구 설정
  • 배포 시 인스턴스가 꺼져있는 경우, ASG가 새 인스턴스 실행 후 배포 진행
• Port Switching으로 인한 일시적 리소스 2배 소모에 대한 대응
  • 후술 한 여러 해결책 중, 서비스 구현에 따라 택1 하여 대응
    1. JVM 힙 메모리 용량 제한(실행 시 -Xmx 옵션 적용)
    2. Swap 메모리 적극적 설정(기본 4GB 설정 예정)
    3. Startup CPU 제어( BE 시작시 CPU 사용률 증가. t3 Burst 기능 사용(기본 동작))
    4. OOM Killer 우선순위 조정 (새로 뜬 프로세스에 높은 점수를 줘 메모리 부족 시 새 프로세스 희생)

필수 설정 사항

• EC2 및 ASG

  • 인스턴스 타입: t3.medium(Spot Instance)

  • 스왑메모리: 4GB

  • 서버 초기 설정 스크립트 (포트스위칭을 위한 Nginx 설정 포함)

    #!/bin/bash
    # 1. 시스템 업데이트 및 필수 패키지 설치
    sudo apt-get update -y
    sudo apt-get install -y ruby wget curl git jq awscli
    
    # 2. Swap 메모리 4GB 설정 (필수)
    sudo fallocate -l 4G /swapfile
    sudo chmod 600 /swapfile
    sudo mkswap /swapfile
    sudo swapon /swapfile
    echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
    
    # 3. CodeDeploy Agent 설치
    cd /home/ubuntu
    wget https://aws-codedeploy-ap-northeast-2.s3.ap-northeast-2.amazonaws.com/latest/install
    chmod +x ./install
    sudo ./install auto
    
    # 4. Runtimes 설치
    # 4-1. Java 21 (Temurin)
    wget -O - https://packages.adoptium.net/artifactory/api/gpg/key/public | sudo apt-key add -
    echo "deb https://packages.adoptium.net/artifactory/deb $(awk -F= '/^VERSION_CODENAME/{print$2}' /etc/os-release) main" | sudo tee /etc/apt/sources.list.d/adoptium.list
    sudo apt-get update
    sudo apt-get install -y temurin-21-jdk
    
    # 5. 디렉토리 구조 생성 및 권한 설정
    # 각 서비스(Backend, Frontend, AI)가 위치할 폴더를 미리 생성합니다.
    mkdir -p /home/ubuntu/apps/{backend,frontend,ai}
    
    # 생성된 폴더의 소유권을 ubuntu 유저에게 부여하여 
    # CodeDeploy Agent(ubuntu 유저로 실행됨)가 쓰기 권한을 갖도록 합니다.
    sudo chown -R ubuntu:ubuntu /home/ubuntu/apps
    
    # 6. [Staging 전용] Nginx Blue/Green 초기 설정 (BE + AI)
    sudo apt-get install -y nginx
    
    # 6-1. Backend용 동적 포트 파일 (기본 8080)
    echo 'set $service_url http://127.0.0.1:8080;' | sudo tee /etc/nginx/conf.d/service-url.inc
    
    # 6-2. AI용 동적 포트 파일 (기본 8000)
    echo 'set $ai_service_url http://127.0.0.1:8000;' | sudo tee /etc/nginx/conf.d/ai-service-url.inc
    
    # 6-3. Nginx 메인 설정 (Reverse Proxy)
    cat <<EOF | sudo tee /etc/nginx/sites-available/default
    server {
        listen 80;
        server_name _;
    
        # Backend (Root)
        include /etc/nginx/conf.d/service-url.inc;
        location / {
            proxy_pass \$service_url;
            proxy_set_header Host \$host;
            proxy_set_header X-Real-IP \$remote_addr;
        }
    
        # AI Server (Prefix: /api/ai 또는 내부 호출용 포트 분리 가능)
        # 여기서는 /ai 경로로 들어오면 AI 서버로 보낸다고 가정
        include /etc/nginx/conf.d/ai-service-url.inc;
        location /ai/ {
            proxy_pass \$ai_service_url;
            proxy_set_header Host \$host;
            proxy_set_header X-Real-IP \$remote_addr;
            # FastAPI 문서(Swagger) 등을 위해 rewrite 필요할 수 있음
            rewrite ^/ai/(.*)\$ /\$1 break;
        }
    }
    EOF
    
    sudo nginx -t
    sudo systemctl restart nginx
    

• AWS CodeDeploy 배포 그룹 설정

  • 배포 유형: In-Place 배포(단일 서버이므로 AWS 입장에서는 In-Place / 내부 스크립트로 Blue/Green 구현)
  • 환경 구성: Auto Scaling Group선택
  • 배포 설정: CodeDeployDefault.OneAtATime
  • IAM Role: AmazonSSMReadOnlyAccess 필수
  • 로드밸런서: 설정 해제(Nginx가 로드밸런서 역할)

• 서비스 별 설정 및 스크립트

  • BE(Spring Boot)

    • 전략: Blue/Green 배포 8080↔ 8081 포트스위칭

    • appspec.yml

      version: 0.0
      os: linux
      files:
        - source: /
          destination: /home/ubuntu/apps/backend
          overwrite: true
      
      permissions:
        - object: /home/ubuntu/apps/backend/scripts
          pattern: "**"
          owner: ubuntu
          group: ubuntu
          mode: 755
      
      hooks:
        # Stop 단계는 생략 (새 버전 띄우고 스위칭 후 종료함)
        ApplicationStart:
          - location: scripts/start.sh
            timeout: 120
            runas: ubuntu
        ValidateService:
          - location: scripts/validate_and_switch.sh
            timeout: 180
            runas: ubuntu
      

    • start.sh (유휴 포트 찾기 및 실행)

      #!/bin/bash
      PROJECT_ROOT="/home/ubuntu/apps/backend"
      DISCORD_SCRIPT="$PROJECT_ROOT/scripts/utils/discord.sh"
      
      cd $PROJECT_ROOT
      
      # 현재 구동 중인 포트 확인 (service-url.inc 파싱)
      CURRENT_PORT=$(grep -oP '127.0.0.1:\K\d+' /etc/nginx/conf.d/service-url.inc)
      
      if [ "$CURRENT_PORT" == "8080" ]; then
        TARGET_PORT=8081
        PROFILE="green"
      else
        TARGET_PORT=8080
        PROFILE="blue"
      fi
      
      # 시작 알림
      bash $DISCORD_SCRIPT "스테이징 배포 시작 (Backend)" "Target Port: $TARGET_PORT ($PROFILE)로 배포를 시작합니다." "info"
      
      # [3] 새 포트에서 앱 실행 (AWS SDK가 환경변수 로드)
      # -Dserver.port 옵션으로 포트 동적 할당
      nohup java -jar -Dserver.port=$TARGET_PORT backend.jar > app.log 2>&1 &
      
      echo ">>> $TARGET_PORT 포트에서 애플리케이션 실행 중..."
      

    • validate_and_switch.sh (검증 및 스위칭 후 기존 서비스 종료)

      #!/bin/bash
      PROJECT_ROOT="/home/ubuntu/apps/backend"
      DISCORD_SCRIPT="$PROJECT_ROOT/scripts/utils/discord.sh"
      
      # 현재 실행하려는 타겟 포트 재확인
      CURRENT_PORT=$(grep -oP '127.0.0.1:\K\d+' /etc/nginx/conf.d/service-url.inc)
      if [ "$CURRENT_PORT" == "8080" ]; then TARGET_PORT=8081; else TARGET_PORT=8080; fi
      
      # Health Check
      echo ">>> Health Check 시작 (Port: $TARGET_PORT)"
      for i in {1..10}; do
        response=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:$TARGET_PORT/health)
        if [ "$response" == "200" ]; then
          break
        fi
        
        # ... (대기 로그) ...
        
        # 자동 롤백 로직
        if [ $i -eq 10 ]; then
           echo ">>> [Auto Rollback] Health Check 실패."
           bash $DISCORD_SCRIPT "배포 실패 & 자동 롤백 (Backend)" "Nginx 전환 없이 신규 프로세스를 종료합니다." "fail"
           
           # 새 프로세스 종료
           PID=$(lsof -t -i:$TARGET_PORT)
           if [ -n "$PID" ]; then kill -15 $PID; fi
           
           exit 1 # CodeDeploy Fail 처리
        fi
      done
      
      # Nginx 스위칭 (트래픽 전환)
      echo ">>> Nginx Port Switching ($CURRENT_PORT -> $TARGET_PORT)"
      echo "set \$service_url http://127.0.0.1:$TARGET_PORT;" | sudo tee /etc/nginx/conf.d/service-url.inc
      sudo nginx -s reload
      
      bash $DISCORD_SCRIPT "배포 완료 (Staging)" "Nginx 포트 전환 완료. ($TARGET_PORT)" "success"
      
      # 구 버전 종료 (Graceful Shutdown)
      echo ">>> 구 버전 프로세스 종료 (Port: $CURRENT_PORT)"
      OLD_PID=$(lsof -t -i:$CURRENT_PORT)
      if [ -n "$OLD_PID" ]; then kill -15 $OLD_PID; fi
      

  • FE(Next.js) + PM2

    • 배포 전략: PM2의 reload 기능 활용하여 무중단 재시작 구현

    • appspec.yml , install.sh, validate.sh 는 개발서버와 동일

    • start.sh

      #!/bin/bash
      PROJECT_ROOT="/home/ubuntu/apps/frontend"
      DISCORD_SCRIPT="$PROJECT_ROOT/scripts/utils/discord.sh"
      
      # 시작 알림
      bash $DISCORD_SCRIPT "스테이징 배포 시작 (Frontend)" "PM2 Zero-downtime Reload를 시도합니다." "info"
      
      cd $PROJECT_ROOT
      
      # PM2 Reload (프로세스가 없으면 Start, 있으면 Reload)
      if pm2 list | grep -q "frontend"; then
          pm2 reload frontend --update-env
          echo ">>> PM2 Reload Complete"
      else
          pm2 start npm --name "frontend" -- start
          echo ">>> PM2 Start Complete"
      fi
      

  • AI(fastAPI)

    • 배포 전략

    • appspec.yml

      version: 0.0
      os: linux
      files:
        - source: /
          destination: /home/ubuntu/apps/ai
          overwrite: true
      permissions:
        - object: /home/ubuntu/apps/ai/scripts
          pattern: "**"
          owner: ubuntu
          group: ubuntu
          mode: 755
      hooks:
        ApplicationStart:
          - location: scripts/start.sh
            timeout: 180
            runas: ubuntu
        ValidateService:
          - location: scripts/validate_and_switch.sh
            timeout: 120
            runas: ubuntu
      

    • start.sh (포트 결정 및 실행)

      #!/bin/bash
      PROJECT_ROOT="/home/ubuntu/apps/ai"
      VENV_PATH="$PROJECT_ROOT/venv"
      DISCORD_SCRIPT="$PROJECT_ROOT/scripts/utils/discord.sh"
      
      cd $PROJECT_ROOT
      
      # 현재 AI 포트 확인 (ai-service-url.inc 파싱)
      CURRENT_PORT=$(grep -oP '127.0.0.1:\K\d+' /etc/nginx/conf.d/ai-service-url.inc)
      
      if [ "$CURRENT_PORT" == "8000" ]; then
        TARGET_PORT=8001
        PROFILE="green"
      else
        TARGET_PORT=8000
        PROFILE="blue"
      fi
      
      bash $DISCORD_SCRIPT "스테이징 배포 시작 (AI)" "Target Port: $TARGET_PORT ($PROFILE)" "info"
      
      # 가상환경 및 패키지 설치
      if [ ! -d "$VENV_PATH" ]; then python3 -m venv $VENV_PATH; fi
      source $VENV_PATH/bin/activate
      pip install -r requirements.txt
      
      # 새 포트에서 앱 실행
      # AWS SDK(boto3)가 코드 레벨에서 환경변수 로드함
      echo ">>> Uvicorn 실행 (Port: $TARGET_PORT)"
      nohup uvicorn main:app --host 0.0.0.0 --port $TARGET_PORT > app.log 2>&1 &
      

    • validate_and_switch.sh (검증 및 자동 롤백 로직)

      #!/bin/bash
      PROJECT_ROOT="/home/ubuntu/apps/ai"
      DISCORD_SCRIPT="$PROJECT_ROOT/scripts/utils/discord.sh"
      
      # 현재 포트와 타겟 포트 다시 확인
      CURRENT_PORT=$(grep -oP '127.0.0.1:\K\d+' /etc/nginx/conf.d/ai-service-url.inc)
      if [ "$CURRENT_PORT" == "8000" ]; then TARGET_PORT=8001; else TARGET_PORT=8000; fi
      
      echo ">>> [Validate] AI Health Check (Port: $TARGET_PORT)"
      
      # Health Check (10회 시도)
      for i in {1..10}; do
        response=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:$TARGET_PORT/health)
        
        if [ "$response" == "200" ]; then
          echo ">>> Health Check 성공!"
          break
        fi
        
        bash $DISCORD_SCRIPT "AI 검증 대기중... ($i/10)" "Port: $TARGET_PORT 응답: $response" "info"
        sleep 5
        
        # 자동 롤백 로직
        if [ $i -eq 10 ]; then
           echo ">>> [Auto Rollback] 배포 실패 감지."
           bash $DISCORD_SCRIPT "배포 실패 & 자동 롤백 (AI)" "Health Check 실패. Nginx를 전환하지 않고 새 프로세스를 종료합니다." "fail"
           
           # 새 프로세스 강제 종료 (롤백 수행)
           # fuser -k -n tcp $TARGET_PORT (또는 kill -9 PID)
           # Ubuntu에서는 fuser가 없을 수 있으므로 pgrep/kill 사용 권장
           PID=$(lsof -t -i:$TARGET_PORT)
           if [ -n "$PID" ]; then kill -9 $PID; fi
      
           # 스크립트 실패 처리 -> CodeDeploy 상태 'Fail'로 기록됨
           exit 1 
        fi
      done
      
      # Nginx 스위칭 (배포 성공 시)
      echo ">>> [Switch] Nginx Port Switching ($CURRENT_PORT -> $TARGET_PORT)"
      echo "set \$ai_service_url http://127.0.0.1:$TARGET_PORT;" | sudo tee /etc/nginx/conf.d/ai-service-url.inc
      sudo nginx -s reload
      
      bash $DISCORD_SCRIPT "배포 완료 (AI)" "Nginx 포트 전환 완료 ($TARGET_PORT). 정상 서비스 중입니다." "success"
      
      # 구 버전 종료 (Graceful Shutdown)
      # 사용자의 AI API 응답 대기를 위해 30초 부여
      echo ">>> [Cleanup] 구 버전 종료 (Port: $CURRENT_PORT)"
      OLD_PID=$(lsof -t -i:$CURRENT_PORT)
      if [ -n "$OLD_PID" ]; then kill -15 $OLD_PID; fi
      

3.2.3. 운영 서버

운영서버 특성

• 안정성 및 가용성이 최우선
• 수동 승인을 트리거로 배포, 보수적인 롤백 및 모니터링 전략 필요

배포 방식 요약

• Blue/Green 배포(포트 스위칭)
• 수동 승인
• 보수적 검증과 롤백
  • 스테이징보다 더 긴 Health Check 및 종료 대기 시간
  • 배포 실패 시 무조건 자동 롤백 실행(트래픽 전환 차단)
  • 배포 성공 후 로직 상 문제 발생 시 CodeDeploy 재배포 기능을 이용한 수동 롤백 가능

필수 설정사항

• 인스턴스 타입: t3.large

• 스왑메모리: 4~8GB

• 서버 초기 설정 스크립트

  • 스테이징 서버와 스왑메모리 및 JVM 힙 메모리 설정 제외 동일.
  • Nginx 설정 동일

• AWS CodeDeploy 배포 그룹 설정

  • 배포 유형: In-Place 배포 (단일 인스턴스 내부 스크립트로 B/G 구현)
  • 환경 구성: CodeDeployDefault.OneAtATime
  • IAM Role: AmazonSSMReadOnlyAccess
  • 로드밸런서: 설정 해제 (Nginx가 역할 대체)
  • 롤백 구성: 배포 실패시 자동 롤백 활성화

• 서비스 별 설정 및 스크립트

  • BE(Spring Boot)

    • appspec.yml : 스테이징과 동일

    • start.sh (메모리 설정 차이)

      #!/bin/bash
      PROJECT_ROOT="/home/ubuntu/apps/backend"
      DISCORD_SCRIPT="$PROJECT_ROOT/scripts/utils/discord.sh"
      
      cd $PROJECT_ROOT
      
      # 현재 구동 중인 포트 확인
      CURRENT_PORT=$(grep -oP '127.0.0.1:\K\d+' /etc/nginx/conf.d/service-url.inc)
      if [ "$CURRENT_PORT" == "8080" ]; then
        TARGET_PORT=8081
        PROFILE="green"
      else
        TARGET_PORT=8080
        PROFILE="blue"
      fi
      
      # 시작 알림
      bash $DISCORD_SCRIPT "운영 배포 시작 (Backend)" "Target Port: $TARGET_PORT ($PROFILE)" "info"
      
      # 새 포트에서 앱 실행 (Prod 환경에 맞춰 메모리 상향)
      # t3.large(8GB) 기준: Heap 2GB~4GB 할당 설정 필요
      nohup java -jar -Xms2048m -Xmx4096m -Dserver.port=$TARGET_PORT backend.jar > app.log 2>&1 &
      
      echo ">>> $TARGET_PORT 포트에서 애플리케이션 실행 중..."
      

    • validate_and_switch.sh (종료 대기 시간 60초 및 헬스체크 수 증가)

      #!/bin/bash
      PROJECT_ROOT="/home/ubuntu/apps/backend"
      DISCORD_SCRIPT="$PROJECT_ROOT/scripts/utils/discord.sh"
      
      CURRENT_PORT=$(grep -oP '127.0.0.1:\K\d+' /etc/nginx/conf.d/service-url.inc)
      if [ "$CURRENT_PORT" == "8080" ]; then TARGET_PORT=8081; else TARGET_PORT=8080; fi
      
      # Health Check (20회 시도)
      echo ">>> Health Check 시작 (Port: $TARGET_PORT)"
      for i in {1..20}; do
        response=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:$TARGET_PORT/health)
        if [ "$response" == "200" ]; then break; fi
      
        bash $DISCORD_SCRIPT "검증 대기중... ($i/20)" "Port: $TARGET_PORT" "info"
        sleep 5
      
        if [ $i -eq 20 ]; then
           bash $DISCORD_SCRIPT "❌ 배포 실패 & 자동 롤백 (Backend)" "Prod Health Check 실패." "fail"
           PID=$(lsof -t -i:$TARGET_PORT)
           if [ -n "$PID" ]; then kill -15 $PID; fi
           exit 1
        fi
      done
      
      # Nginx 스위칭
      echo "set \$service_url http://127.0.0.1:$TARGET_PORT;" | sudo tee /etc/nginx/conf.d/service-url.inc
      sudo nginx -s reload
      
      bash $DISCORD_SCRIPT "배포 완료 (Production)" "Nginx 포트 전환 완료. ($TARGET_PORT)" "success"
      
      # 구 버전 종료 (Grace Period 60초 + graceful down 30초)
      echo ">>> 기존 연결 종료 대기 (60초)..."
      sleep 60
      OLD_PID=$(lsof -t -i:$CURRENT_PORT)
      if [ -n "$OLD_PID" ]; then kill -15 $OLD_PID;
      fi
      

  • FE(Next.js)

    • 스테이징 서버와 동일한 무중단 배포 전략
    • 스테이징 서버와 스크립트 전체 동일

  • AI(FastAPI)

    • start.sh : 스테이징 서버와 동일

    • validate_and_switch.sh: Grace Period 60초 적용. 긴 추론 요청이 끊기지 않도록 보호.

      #!/bin/bash
      PROJECT_ROOT="/home/ubuntu/apps/ai"
      DISCORD_SCRIPT="$PROJECT_ROOT/scripts/utils/discord.sh"
      
      # 현재 포트와 타겟 포트 다시 확인
      CURRENT_PORT=$(grep -oP '127.0.0.1:\K\d+' /etc/nginx/conf.d/ai-service-url.inc)
      if [ "$CURRENT_PORT" == "8000" ]; then TARGET_PORT=8001; else TARGET_PORT=8000; fi
      
      echo ">>> [Validate] AI Health Check (Port: $TARGET_PORT)"
      
      # Health Check (10회 시도)
      for i in {1..10}; do
        response=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:$TARGET_PORT/health)
        
        if [ "$response" == "200" ]; then
          echo ">>> Health Check 성공!"
          break
        fi
        
        bash $DISCORD_SCRIPT "AI 검증 대기중... ($i/10)" "Port: $TARGET_PORT 응답: $response" "info"
        sleep 5
        
        # 자동 롤백 로직
        if [ $i -eq 10 ]; then
           echo ">>> [Auto Rollback] 배포 실패 감지."
           bash $DISCORD_SCRIPT "배포 실패 & 자동 롤백 (AI)" "Health Check 실패. Nginx를 전환하지 않고 새 프로세스를 종료합니다." "fail"
           
           # 새 프로세스 강제 종료 (롤백 수행)
           # fuser -k -n tcp $TARGET_PORT (또는 kill -9 PID)
           # Ubuntu에서는 fuser가 없을 수 있으므로 pgrep/kill 사용 권장
           PID=$(lsof -t -i:$TARGET_PORT)
           if [ -n "$PID" ]; then kill -9 $PID; fi
      
           # 스크립트 실패 처리 -> CodeDeploy 상태 'Fail'로 기록됨
           exit 1 
        fi
      done
      
      # Nginx 스위칭 (배포 성공 시)
      echo ">>> [Switch] Nginx Port Switching ($CURRENT_PORT -> $TARGET_PORT)"
      echo "set \$ai_service_url http://127.0.0.1:$TARGET_PORT;" | sudo tee /etc/nginx/conf.d/ai-service-url.inc
      sudo nginx -s reload
      
      bash $DISCORD_SCRIPT "배포 완료 (AI)" "Nginx 포트 전환 완료 ($TARGET_PORT). 정상 서비스 중입니다." "success"
      
      # 구 버전 종료 (AI 요청 보호를 위해 60초 대기)
      echo ">>> 기존 AI 요청 종료 대기 (60초)..."
      sleep 60
      OLD_PID=$(lsof -t -i:$CURRENT_PORT)
      if [ -n "$OLD_PID" ]; then kill -15 $OLD_PID; fi
      ``
      
      
      

4. 기술적 구현 명세

배포 파이프라인을 실제 인프라 환경에서 구현하기 위한 기술적 세부사항 및 설정 값 정의

4.1. 무중단 배포 아키텍처

• 동적 포트 라우팅 (Dynamic Port Routing)
  • Nginx가 고정된 포트가 아닌, 별도의 설정 파일을 통해 동적으로 프록시 대상을 변경할 수 있도록 구성
  • 매커니즘
    1. 배포 로직 시작 시 Idle 포트를 식별하여 애플리케이션 구동
    2. Health Check 성공 시, service-url.inc 파일의 포트 정보 덮어쓰기
    3. nginx -s reload 명령어를 통해 무중단 설정 갱신
• 포트 결정 로직
  • 현재 실행중인 포트를 확인 후, 배포 할 타켓 포트를 결정.
  • 포트 감지: grep 명령어로 service-url.inc 파일 내부의 포트 번호 추출
  • 이후 포트 토글 로직을 통해 변경

4.2. 런타임 및 리소스 최적화

단일 인스턴스 내에서 다수의 서비스(BE, FE, AI, Nginx)가 동시에 구동되므로, 엄격한 리소스 관리, 최적화가 요구됨.

• JVM 메모리 제어
  • 배포 시 일시적으로 두개의 애플리케이션이 동시에 실행되는 구간 발생
  • OOM(메모리 부족)으로 인한 종료를 방지하기 위해 힙 메모리를 제한
  • 배포 순간의 메모리 스파이크 방지를 위한 Xms, Xmx 힙 메모리 제한 설정.
• Swap Memory 활용
  • 물리 메모리 부족(OOM) 상황을 방어하기 위해 서버별로 4~8GB Swap 메모리 설정
  • fallocate를 사용하여 스왑 파일을 생성, /etc/fstab에 등록하여 재부팅 후에도 설정 유지
• 서비스 격리
  • 각 서비스 간 상호 간섭이 발생하지 않도록 독립된 디렉토리를 구성
  • 디렉토리 구조
    • BE: /home/ubuntu/apps/be
    • FE: /home/ubuntu/apps/fe
    • AI: /home/ubuntu/apps/ai

4.3. AWS CodeDeploy 구성

AWS CodeDeploy의 Lifecycle Hooks 를 사용하여 배포 단계 세분화 및 단계별 스크립트 모듈화

4.3.1. Lifecycle Hooks

• ApplicationStop
  • 기존 실행 중인 서비스 프로세스 확인 및 종료
  • B/G 배포 시 생략 (배포 실패 시 리소스 정리에 사용 가능)
• AfterInstall
  • S3에서 다운로드 한 Artifact의 권한 설정, 의존성 설치 진행
• ApplicationStart
  • 각 서비스 및 어플리케이션을 백그라운드 모드로 실행(nohup, pm2)
  • JVM 옵션, 포트 설정 등 실행시점 설정내용 정리
• ValidateService
  • 실행 된 서비스의 Health Check 수행
  • 검증 성공 시 Port Switch 및 구 버전 어플리케이션 프로세스 종료

4.3.2. 스크립트 모듈화

서비스별, 기능별로 스크립트를 분할하여 유지보수성 확보, 중복 감소

• scripts/start.sh: 애플리케이션 구동 및 포트 할당
• scripts/stop.sh: 프로세스 식별 및 종료 (Graceful Shutdown)
• scripts/validate_and_switch.sh: 헬스 체크, Nginx Reload, 구 버전 정리

4.4. 보안 강화 설정

• AWS ParameterStore에서 환경변수 주입
  • .env 파일 작성 및 전송을 통한 환경변수 주입은 보안 위험을 야기(평문 키 및 PW 노출, 휴먼에러 등)
  • 모든 민감정보를 암호화 하여 저장 및 관리
  • 서버 내 애플리케이션 구동 시 AWS SDK를 통해 메모리에 값 로드

5. 모니터링 및 운영

배포 파이프라인의 상태를 실시간 추적, 운영 장애 감지 및 전파, 데이터 보호를 위한 전략 수립

5.1. 실시간 배포 알림 시스템

CodeDeploy 알림은 단순 성공/실패 여부만 확인 가능. 각 단계별(시작, 검증, 종료 및 결과)와 상세한 원인을 즉각 인지할 수 있도록 알림 시스템을 구축

• discord.sh

  • 디스코드 알림을 위한 스크립트
  • curl을 캡슐화하여 재사용성을 높인 쉘 스크립트 모듈 구현.
  • Webhook URL을 하드코딩하지 않고 AWS Parameter Store에서 조회하여 보안 강화
  • 파일 경로: /home/ubuntu/apps/{service}/scripts/utils/discord.sh (서비스별로 각각 포함)
  • 권한: 755

  #!/bin/bash
  
  # ------------------------------------------------------------------
  # Usage: ./discord.sh "Title" "Description" "Status(success/fail/info)"
  # ------------------------------------------------------------------
  
  TITLE=$1
  MESSAGE=$2
  STATUS=$3
  
  # Webhook URL
  # AWS Parameter Store에서 Webhook URL 조회
  # 리전은 서울(ap-northeast-2)로 고정
  WEBHOOK_URL=$(aws ssm get-parameter \
    --name "/global/discord_webhook" \
    --with-decryption \
    --query Parameter.Value \
    --output text \
    --region ap-northeast-2)
  
  # Status Color
  if [ "$STATUS" == "fail" ]; then
    COLOR=16711680 # Red (장애/실패)
  elif [ "$STATUS" == "success" ]; then
    COLOR=65280    # Green (성공/복구)
  else
    COLOR=3447003  # Blue (진행 중/정보)
  fi
  
  # Payload
  # JSON 포맷팅. 줄바꿈 문자 등을 처리하기 위해 cat <<EOF
  PAYLOAD=$(cat <<EOF
  {
    "username": "Deploy Bot",
    "avatar_url": "https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png",
    "embeds": [{
      "title": "${TITLE}",
      "description": "${MESSAGE}",
      "color": ${COLOR},
      "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%S.000Z)",
      "footer": {
        "text": "AWS CodeDeploy • $(hostname)"
      }
    }]
  }
  EOF
  )
  
  # 알림 발송
  # curl을 사용하여 비동기 전송
  curl -H "Content-Type: application/json" -d "$PAYLOAD" "$WEBHOOK_URL" > /dev/null 2>&1
  

• 단계별 상태 중계: 시작, 성공, 실패

• 에러 핸들링 자동화: 리눅스 trap 명령어를 활용, 스크립트 비정상 종료 시 즉시 알림 전송.(개별 배포 스크립트에 포함)

5.2. 리소스 및 로그 모니터링

단일 인스턴스 내 다중 서비스 구동에 맞게 개별 서비스 상태를 파악하기 위한 모니터링 필요

5.2.1. 인스턴스 리소스 모니터링(CloudWatch)

• 대상: 인스턴스 리소스(CPU 사용률, 메모리 점유율, 디스크 I/O, SWap 사용량, 네트워크 등)
• 설정: AWS CloudWatch Agent를 설치하여 인스턴스 내부 지표 수집
• 알림 설정
  • CPU 사용률 80% 이상 5분 지속시 알림
  • 메모리 여유공간 500MB 이하시 즉시 알림(OOM 경고)

5.2.2. 로그 파일 관리

디스크 용량 부족을 위한 로그파일 관리 정책 수립

로그파일을 자동으로 압축, 백업 삭제, 로테이션을 수행하는 유틸리티(logrotate) 사용

• 로그 경로

  • Backend: /home/ubuntu/apps/backend/app.log
  • Frontend: ~/.pm2/logs/ (PM2에서 관리)
  • AI: /home/ubuntu/apps/ai/app.log
  • CodeDeploy: /var/log/aws/codedeploy-agent/

• Logrotate설정: 리눅스 Logrotate 유틸리티 사용하여 일별 순환, 최대 7일 보관, 압축

  # 대상 로그 파일 경로
  /home/ubuntu/apps/be/*.log
  /home/ubuntu/apps/ai/*.log
  /home/ubuntu/apps/fe/*.log 
  /var/log/aws/codedeploy-agent/codedeploy-agent.log
  {
      daily           # 매일 로테이트 실행
      missingok       # 로그 파일이 없어도 에러 없이 넘어감
      rotate30        # 최근 30개(30일치) 파일만 보관하고 나머지는 삭제
      compress        # 지난 로그 파일은 gzip으로 압축하여 용량 절약 (.gz)
      delaycompress   # 압축을 바로 하지 않고 하루 뒤에 수행 (현재 쓰기 중인 파일 보호)
      notifempty      # 로그 내용이 비어있으면 로테이트 하지 않음
      copytruncate    # 핵심: 현재 로그 파일을 복사(copy) 후 원본 내용을 비움(truncate).
                      # 프로세스 재시작 없이 로그 파일을 나눌 수 있는 가장 안전한 방법.
      create 0644 ubuntu ubuntu # 새 로그 파일 생성 시 권한 및 소유자 지정
      dateext         # 백업 파일명에 날짜 추가 (app.log-20240101.gz)
  }
  

5.2.3. Artifact 관리

빌드 결과물인 Artifact가 과도하게 쌓여 비용적, 성능적 문제를 일으키는 것을 방지하기 위해 Lifecycle 관리

• 적용 대상: S3 내부의 빌드 산출물 객체 전체
• 정책
  • Transition to IA(Infrequent Access)
    • 자주 접근하지 않는 오래된 빌드파일은 저렴한 스토리지클래스(Standard-IA)로 이동하여 보관 비용 약 40% 절약(서울 리전 기준 일반 S3 GB당 USD 0.025 / AI GB당 USD0.011로 50% 이상 비용 절감
  • Expiration
    • 생성 후 90일(3개월)이 지난 코드로 롤백하는 경우는 없음.
    • 영구 삭제하여 비용 누수 차단

5.3. 데이터 보호 및 백업

배포 실패, 인스턴스 장애 등으로 인한 데이터 유실을 방지하기 위한 전략 수립

5.3.1. 데이터베이스 백업

• 로컬 DB 데이터를 보존하기 위해 EBS 볼륨 스냅샷을 주기적으로 생성
  • 사용자가 적어 성능 영향이 적은 새벽 2~5시 사이에 스냅샷 생성 및 관리

5.3.2. CodeDeploy 배포 이력

• AWS CodeDeploy의 배포 이력 보존을 통해 기록 확인 및 롤백 가능

5.4. 장애 전파 및 대응

서버 운영 시 발생할 수 있는 장애 시나리오 별 대응 절차

5.4.1. 배포 직후 Health Check 실패

• 서버 내부 배포 스크립트 중 validate_and_switch.sh가 감지하여 exit1 반환
• 자동 롤백 설정이 된 경우 CodeDeploy가 배포 상태 확인 후 자동 롤백 트리거
• 트래픽 변경이 없어 구 버전 유지 → 사용자 영향 없음

5.4.2. 배포 성공 후 로직 오류 발견

• 디버깅, QA, 각종 알림 등을 통해 개발 및 운영진이 오류 인지
• GitHub Actions에서 이전 버전으로 롤백 트리거 및 재배포 파이프라인 실행

5.4.3. 서버 다운

• 스테이징 서버: ASG가 HealthCheck 실패 감지 후 새 인스턴스 자동 실행 및 배포 로직 실행
• 운영 서버: ASG를 통한 자동 복구 및 CloudWatch를 통한 알림 전파