Module 05

신규 프로젝트 부트스트랩 — 처음부터 배포까지

13가지 변수 준비 → 11 STEP → CloudFront URL 확인까지

신규 프로젝트 부트스트랩

새 프로젝트에 Azure AD SSO + 서버리스 배포를 처음부터 적용하는 가이드

사전 준비 — 13가지 변수를 먼저 모아두자

시작 전에 아래 13가지 정보를 메모장에 모아두세요. 부트스트랩 과정에서 이 값들이 필요합니다. 특히 Azure Tenant ID, Client ID는 Azure Portal에서 확인해야 합니다.

AZURE_TENANT_ID

Azure AD → 앱 등록 → 해당 앱 → 개요 → 디렉터리(테넌트) ID

AZURE_CLIENT_ID

Azure AD → 앱 등록 → 해당 앱 → 개요 → 애플리케이션(클라이언트) ID

AWS_PROFILE

~/.aws/credentials의 프로파일 이름 (예: gsr-dev)

AWS_REGION

ap-northeast-2 (서울)

PROJECT_NAME

gsr- 로 시작하는 프로젝트 이름 (예: gsr-my-project). Lambda 함수명이 됨

LAMBDA_ROLE_ARN

IAM → 역할 → 사전 생성한 Lambda 역할 ARN. 없으면 Module 04 참조하여 생성

ZAPPA_S3_BUCKET

Zappa 배포 패키지를 올릴 S3 버킷 이름 (임시 저장소)

FRONTEND_S3_BUCKET

Next.js 빌드 파일을 올릴 S3 버킷 이름

CLOUDFRONT_DIST_ID

기존 CloudFront 재사용 시: 배포 ID. 신규 생성 시: 나중에 기록

CLOUDFRONT_URL

https://xxxx.cloudfront.net — Azure Portal 리다이렉트 URI 등록에 사용

DYNAMODB_TABLE

로그인 이력 저장 테이블 이름 (gsr-로 시작 권장)

PYTHON_PATH

/opt/homebrew/opt/python@3.12/bin/python3.12

API_BASE_URL

zappa deploy 완료 후 출력되는 API Gateway URL. 나중에 기록

ℹ️ CloudFront는 재사용할 수 있습니다. 기존 프로젝트에서 생성한 CloudFront 배포를 새 프로젝트 S3 버킷으로 교체하면 됩니다. 비용도 절약되고 URL도 안정적입니다. 단, 기존 배포의 오리진(Origin)을 새 버킷으로 변경해야 합니다.

11 STEP 부트스트랩 흐름

gsr-sso-sample 레포 클론 + 새 프로젝트로 복사

gsr-sso-sample 레포를 클론하고 samples/ 폴더를 새 프로젝트 폴더로 복사합니다.

git clone <gsr-sso-sample-repo>
cp -r gsr-sso-sample/samples/ my-new-project/

Python 3.12 가상환경 생성 + 의존성 설치

반드시 Python 3.12 전체 경로로 가상환경을 만들어야 합니다.

cd my-new-project/api
/opt/homebrew/opt/python@3.12/bin/python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

zappa_settings.json 작성

준비한 13가지 변수로 zappa_settings.json을 작성합니다. Module 02의 설정 예시를 참고하세요.

# zappa_settings.json의 핵심 필드 채우기
project_name: "gsr-my-project"
role_arn: "arn:aws:iam::123:role/..."
s3_bucket: "my-zappa-bucket"
profile_name: "gsr-dev"
api_gateway_endpoint_type: "REGIONAL"
use_precompiled_packages: true
manylinux: true
ephemeral_storage: {"Size": 1024}

.env 파일 작성

백엔드 .env 파일에 Azure AD 정보와 DynamoDB 테이블 이름을 작성합니다.

AZURE_TENANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
DYNAMODB_TABLE_NAME=gsr-my-project-login-history
AWS_DEFAULT_REGION=ap-northeast-2

DynamoDB 테이블 생성 (AWS 콘솔 또는 CLI)

로그인 이력을 저장할 테이블을 먼저 만들어야 합니다. Partition Key: user_id (String), Sort Key: login_time (String).

zappa deploy — 최초 Lambda + API GW 생성

처음 배포할 때만 deploy를 사용합니다. 이후 코드 변경 시에는 update를 씁니다.

cd my-new-project/api
source venv/bin/activate
zappa deploy prod
# 완료 후 출력되는 API Gateway URL을 API_BASE_URL로 기록

Lambda ephemeral storage 확인 + 필요 시 수동 설정

Lambda 콘솔에서 임시 스토리지가 1024 MB인지 확인합니다. 512 MB이면 수동으로 변경합니다.

S3 버킷 생성 + CloudFront 구성

프론트엔드용 S3 버킷을 생성하고 퍼블릭 액세스를 차단합니다. CloudFront 배포를 생성하고 OAC를 연결합니다. S3 버킷 정책에 CloudFront OAC 허용 정책을 추가합니다.

Azure Portal 리다이렉트 URI 등록

CloudFront URL과 localhost를 Azure Portal에 등록합니다. (Module 03 참조)

# 등록할 URI 목록
https://xxxx.cloudfront.net
http://localhost:3000

Next.js 환경변수 설정 + 빌드

.env.production에 CloudFront URL과 API URL을 설정하고 빌드합니다.

# frontend/.env.production
NEXT_PUBLIC_API_URL=https://yyyy.execute-api.ap-northeast-2.amazonaws.com/prod
NEXT_PUBLIC_AZURE_TENANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
NEXT_PUBLIC_AZURE_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
NEXT_PUBLIC_REDIRECT_URI=https://xxxx.cloudfront.net

# 빌드
cd frontend
pnpm build  # out/ 폴더 생성

S3 업로드 + CloudFront 캐시 무효화

빌드된 out/ 폴더를 S3에 업로드하고 CloudFront 캐시를 무효화합니다.

aws s3 sync out/ s3://my-frontend-bucket/ --profile gsr-dev
aws cloudfront create-invalidation \
  --distribution-id E1234567890 \
  --paths "/*" \
  --profile gsr-dev

✅ 11 STEP 완료 후 https://xxxx.cloudfront.net에서 앱이 동작해야 합니다.

Claude Code 프롬프트 — 원샷 부트스트랩

"13가지 변수를 모두 준비했다면 Claude Code에게 한 번에 맡길 수 있습니다."

gsr-sso-sample 레포의 doc/new_project_bootstrap.md에 포함된 Claude Code 프롬프트 템플릿입니다. 13가지 변수를 채워서 Claude Code에게 전달하면 STEP 1~11을 자동으로 실행합니다.

📋 Claude Code 프롬프트 템플릿

gsr-sso-sample 레포를 참고해서 새 프로젝트를 부트스트랩해줘.

## 변수 (모두 채워줘)
- PROJECT_NAME: gsr-my-project
- AZURE_TENANT_ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- AZURE_CLIENT_ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- AWS_PROFILE: gsr-dev
- LAMBDA_ROLE_ARN: arn:aws:iam::123456789:role/gsr-lambda-role
- ZAPPA_S3_BUCKET: gsr-zappa-deploy-bucket
- FRONTEND_S3_BUCKET: gsr-my-project-frontend
- CLOUDFRONT_DIST_ID: (기존 재사용 시 입력, 신규 생성 시 비워둬)
- DYNAMODB_TABLE: gsr-my-project-login-history

## 해야 할 일
1. samples/ 폴더 복사 + 프로젝트 이름 변경
2. Python 3.12 venv 생성 + 의존성 설치
3. zappa_settings.json 작성 (manylinux, REGIONAL, ephemeral 1024)
4. .env 파일 작성
5. DynamoDB 테이블 생성
6. zappa deploy
7. ephemeral storage 확인 (Lambda 콘솔)
8. S3 버킷 생성 + CloudFront OAC 구성
9. Next.js .env.production 작성 + 빌드
10. S3 sync + CloudFront 캐시 무효화
11. 동작 확인: CloudFront URL에서 로그인 테스트

각 STEP 완료 후 다음 STEP로 진행해줘. 막히는 부분은 보고해줘.

배포 완료 검증 3단계

1단계: 백엔드 health check — curl https://yyyy.execute-api.../prod/api/health가 200 응답을 반환하는지 확인
2단계: 프론트엔드 로드 — CloudFront URL에서 로그인 버튼이 보이는지 확인
3단계: E2E 로그인 — 사내 Microsoft 계정으로 로그인 → JWT claims 표시 → DynamoDB에 로그인 이력 기록 확인

자주 하는 실수 TOP 5

순위	실수	증상	해결
1	`zappa deploy`를 재배포 시 사용	"Function already exists" 오류	`zappa update prod` 사용
2	ephemeral storage 확인 안 함	`No space left on device` 또는 ImportError	Lambda 콘솔에서 1024MB로 수동 변경
3	Azure Portal 리다이렉트 URI 미등록	로그인 시 AADSTS50011 오류	CloudFront URL과 localhost 등록
4	CORS 설정을 Flask-CORS만	OPTIONS preflight 실패	zappa_settings.json에 `"cors": true` 추가
5	React 19 사용	빌드 실패 또는 SSR 오류	React 18.3.1로 고정

✅ 이 모듈을 마쳤습니다. 13가지 변수 준비, 11 STEP 부트스트랩 흐름, Claude Code 프롬프트 템플릿, 검증 3단계, 자주 하는 실수까지 — 신규 프로젝트를 처음부터 끝까지 배포할 수 있습니다.