[goodjunseon]

🔗 관련 이슈

메인 이슈

• Passtival 인프라 구축 작업 정리 및 담당자 배정 #236 (Passtival 인프라 구축 작업 정리 및 담당자 배정)

👥 담당자 배정

• GitHub Actions 및 Docker Compose 구조 리팩토링 #237 : @goodjunseon
• GitHub Actions deploy.yml 개선 및 SSM 기반 배포 방식 전환 #238 : @goodjunseon
• CloudFront 기반 정적 파일(CDN) 구조 적용 및 이미지 업로드 흐름 정리 #242 : @jae-2024

📌 배경

이번 PR은 dev 브랜치의 인프라 관련 변경을 main으로 배포하기 위한 머지 PR이며, 범위는 아래 3개 서브이슈의 변경으로 제한합니다.

• refactor/237-unify-compose-and-cleanup
• feat/238-ssm-deploy-pipeline-refactor
• refactor/242-cloudfront-cdn-s3

✅ 변경 사항

1) #237 Compose 진입점 단일화 및 실행 흐름 정리

• docker-compose.dev.yml, docker-compose.prod.yml 제거 후 docker-compose.yml 단일화
• run.sh 실행 모드 정리
  • DEPLOY_MODE=local|prod 분기
  • 운영(prod) 시 DOCKER_USERNAME 외부 주입 필수
  • 로컬 fallback (${DOCKER_USERNAME:-local}) 적용
• .env.example 제거 및 .gitignore 규칙 정리
• Spring 프로필 파일 통합
  • application-dev.yml, application-prod.yml 제거
  • application.yml 단일 관리로 전환
• 운영 가이드(document/docker-guide.md) 최신화

2) #238 OIDC + SSM 롤링 배포 파이프라인 리팩터링

• .github/workflows/deploy.yml에서 CI/Deploy 역할 분리
  • pull_request(main, dev)에서는 ci 검증 중심
  • 실제 배포는 main push 및 workflow_dispatch(main)에서만 실행
• Docker Buildx 및 GitHub Actions 캐시 기반 이미지 빌드/푸시 정리
• 배포 인증 체계를 SSH에서 GitHub OIDC + AWS AssumeRole 방식으로 전환
• AWS SSM으로 2개 인스턴스 순차 롤링 배포
  • 인스턴스 1 성공 후 인스턴스 2 진행
• 배포 readiness 게이트 도입
  • 의존성: spring-boot-starter-actuator
  • 경로: /actuator/health/readiness
  • 보안 설정: /actuator/health/** 허용
• 배포 변수/시크릿 계약 문서화 (document/docker-guide.md)

3) #242 CloudFront 기반 S3 업로드 구조 개선

• Presigned URL 응답 DTO 도입
  • uploadUrl, objectKey, fileUrl
• S3 object key 생성 규칙 개선
  • 경로에 year 포함
  • 파일명 UUID 기반 생성으로 충돌 위험 완화
• 이미지 조회 URL을 CloudFront 도메인 기반으로 반환하도록 변경
• application.yml에 CloudFront 도메인 및 presigned URL 만료 설정 반영

🔄 Public API / Interface 변경

API 응답 변경

• GET /api/s3/upload-url
  • 응답 데이터 구조를 PresignedUrlResponse 중심으로 명시
  • 필드: uploadUrl, objectKey, fileUrl

배포 인터페이스(필수 입력 계약)

• GitHub Secrets
  • DOCKER_USERNAME
  • DOCKER_PASSWORD
  • AWS_ROLE_TO_ASSUME
• GitHub Variables
  • AWS_REGION
  • DEPLOY_DIR
  • DEPLOY_ENV_PATH
  • DEPLOY_MOUNT_PATH
  • EC2_TARGET_TAG_KEY
  • EC2_TARGET_TAG_VALUE
  • HEALTHCHECK_PATH
  • HEALTHCHECK_TIMEOUT_SECONDS
• 서버 실행 인자(run.sh)
  • DOCKER_USERNAME
  • ENV_FILE_PATH
  • DEPLOY_MOUNT_PATH
  • IMAGE_TAG
  • DEPLOY_MODE

🧪 검증 항목 (PR 체크리스트)

CI/배포 파이프라인

• PR 이벤트에서 ci 잡 빌드 통과 확인
• main 배포 시 deploy 잡에서 인스턴스 1 → 인스턴스 2 순차 성공 확인
• 각 인스턴스에서 /actuator/health/readiness 응답 성공 확인

런타임/기능

• GET /api/s3/upload-url 응답에 uploadUrl/objectKey/fileUrl 존재 확인
• fileUrl이 CloudFront 도메인 + objectKey 조합인지 확인

문서/운영

• document/docker-guide.md의 Secrets/Variables 계약과 워크플로우 입력 키 일치 확인

⚠️ 제외 범위

• 이번 PR 본문 상세에는 dev 누적 커밋 중 GitHub Actions 및 Docker Compose 구조 리팩토링 #237/GitHub Actions deploy.yml 개선 및 SSM 기반 배포 방식 전환 #238/CloudFront 기반 정적 파일(CDN) 구조 적용 및 이미지 업로드 흐름 정리 #242 외 변경사항을 포함하지 않음