AWS & GitHub 초기 세팅 가이드

01. 문서 개요

Architecture

Vue.js + FastAPI + AWS Serverless

Target Repo

Asirante/weather-fit

Essential Check

모든 팀원이 동일한 리전(us-east-1, 버지니아 북부)을 사용해야 합니다. 리전이 다르면 데이터 전송 비용이 발생하며 서비스 간 연동이 불가능할 수 있습니다. AWS 콘솔 우측 상단에서 리전을 반드시 확인하세요.

02. GitHub 레포지토리 구성

2.1 모노레포 폴더 구조

project-root/
├── .github/workflows/          # GitHub Actions 워크플로 (FE/BE/DATA/REAL-TIME)
│   ├── deploy-frontend.yml     # frontend/** 변경 시 S3 배포
│   ├── deploy-backend.yml      # backend/** 변경 시 Lambda 업데이트
│   ├── deploy-data-pipeline.yml  # data_pipeline/** 변경 시 Lambda 업데이트
│   └── deploy-real-time.yml    # real_time/** 변경 시 Lambda 업데이트
├── frontend/                   # Vue.js 3 + Vite
├── backend/                    # FastAPI + Mangum (추천 API)
├── data_pipeline/              # EventBridge + Lambda (정기 수집 + 배치 추론)
├── real_time/                  # EventBridge + Lambda (30분 실시간 수집)
├── infra/                      # SAM template.yaml (공통 인프라 정의)
└── README.md

03. GitHub Actions & OIDC 연동

1 GitHub Secrets에 Role ARN 등록 Team Leader

학교 측으로부터 발급받은 배포용 IAM Role ARN을 깃허브에 등록합니다.

Path: Settings > Secrets and variables > Actions
Name: AWS_ROLE_ARN
Value: arn:aws:iam::[계정ID]:role/[역할이름]

2 워크플로 YAML 권한 설정 All Members

OIDC 토큰 발급을 위해 각 .yml 파일의 jobs 하위에 아래 권한 블록을 반드시 추가합니다.

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read

3 AWS 로그인 스텝 추가

배포 명령어 실행 직전에 aws-actions/configure-aws-credentials를 배치합니다. 리전은 반드시 us-east-1으로 설정합니다.

- name: Configure AWS credentials using OIDC
  uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
    aws-region: us-east-1   # 버지니아 북부 리전 (팀 통일)

04. AWS SAM & 협업 가이드

브랜치 운영 및 병합 규칙

main ------------------ 운영 배포 (직접 Push 절대 금지) ㄴ develop ---------- 통합 테스트 / 개발 배포 ㄴ feature/* --- 개별 기능 개발 (feature/weather-api 등)

PR 필수: feature/*에서 develop 병합 시 최소 1명 이상의 리뷰 승인이 필요합니다.
Squash and Merge: 커밋 로그 관리를 위해 반드시 Squash and merge 방식을 선택하세요.

AWS SAM 핵심 워크플로

로컬 빌드 및 테스트

sam build sam local start-api

배포 및 상태 확인

sam deploy --guided --region us-east-1 sam logs -n inhatc-team2-1-recommendAPI

실제 배포 명령어 (YAML 반영용)

Frontend (S3)

aws s3 sync frontend/dist/ s3://inhatc-team2-3-frontend --delete

Backend / Data Pipeline / Real-time (Lambda)

# 백엔드
cd backend && zip -r ../deploy.zip .
aws lambda update-function-code \
  --function-name inhatc-team2-1-recommendAPI \
  --zip-file fileb://../deploy.zip

# 데이터 파이프라인
cd data_pipeline && zip -r ../deploy.zip .
aws lambda update-function-code \
  --function-name inhatc-team2-5-dataAPI \
  --zip-file fileb://../deploy.zip

# 실시간 파이프라인
cd real_time && zip -r ../deploy.zip .
aws lambda update-function-code \
  --function-name inhatc-team2-5-real-time-dataAPI \
  --zip-file fileb://../deploy.zip