AWS Deployment

사전 요구 사항

• Node.js 22 LTS
• AWS CLI 로그인
• AWS CDK bootstrap 완료
• Google OAuth application
• GitHub OAuth application
• Cloudflare Pages project

기본 리전 예시는 ap-southeast-2입니다.

OAuth Callback

두 OAuth application에 다음 callback URL을 등록합니다.

Google: https://<frontend-domain>/api/auth/social/google/callback
GitHub: https://<frontend-domain>/api/auth/social/github/callback

CDK 배포

npm install
npm run build
npm run cdk:deploy -- \
  --parameters FrontendOrigin=https://app.example.com \
  --parameters CognitoDomainPrefix=education-for-kids-example \
  --parameters GoogleClientId=... \
  --parameters GoogleClientSecret=... \
  --parameters GitHubClientId=...

주요 output:

• UserPoolId
• UserPoolClientId
• GitHubUserPoolClientId
• CognitoDomain
• UserDataTableName
• ApiFunctionName
• ApiOriginUrl
• GitHubClientSecretArn

GitHub Secret 등록

CDK 배포 후 실제 GitHub OAuth client secret을 Secrets Manager에 저장합니다.

aws secretsmanager put-secret-value \
  --secret-id <GitHubClientSecretArn> \
  --secret-string '<github-client-secret>'

secret 값은 저장소나 CloudFormation parameter에 직접 기록하지 않습니다.

Cloudflare 연결

Cloudflare Pages 환경 변수에 다음 값을 설정합니다.

AWS_API_ORIGIN=<CDK ApiOriginUrl>

Frontend의 functions/api/[[path]].ts가 /api/* 요청, redirect, 다중 Set-Cookie header를 API Gateway와 브라우저 사이에서 전달합니다.

개발팀 문서 사이트

../Docs 저장소는 사용자 애플리케이션과 분리된 eduboard-docs Cloudflare Pages 프로젝트로 배포합니다. 문서에는 이 디렉터리의 Backend 설계, API, 배포, 비용 문서가 포함됩니다.

Backend 문서를 변경한 후 Docs 저장소에서 동기화와 검증을 실행합니다.

cd ../Docs
npm run docs:sync
npm run docs:sync:check
npm run typecheck
npm run build

문서 호스트 전체는 Cloudflare Access Self-hosted application으로 보호합니다. 개발팀 GitHub organization/team만 허용하고 independent MFA를 필수로 설정합니다. Custom domain뿐 아니라 Pages production pages.dev 주소와 preview deployment에도 Access 정책을 적용해 우회 접근을 차단합니다.

최초 관리자 권한

최초 관리자는 배포 후 DynamoDB ACCESS item의 permissions에 PERMISSION_MANAGE를 추가해야 합니다. 이후부터는 권한 관리 API를 사용합니다.

{
  "pk": "USER#<cognito-sub>",
  "sk": "ACCESS",
  "permissions": ["PERMISSION_MANAGE"]
}

배포 전 검증

npm run build
npm test
npm run cdk:synth
npm audit

합성된 CloudFormation에는 EC2, Auto Scaling, ALB, ECR 리소스가 포함되지 않아야 합니다.

롤백과 데이터 보존

• Cognito User Pool: RETAIN
• DynamoDB table: RETAIN
• DynamoDB PITR: 활성화
• API access log group: stack 삭제 시 제거

인증 사용자와 사용자 데이터는 stack 삭제만으로 제거되지 않습니다.