README.md

TripFit 배포 (deploy/)

TripFit 서버의 로컬 개발 구동, EC2 4대 인프라 배포 절차, HTTPS 인증서 발급 및 운영 스크립트 실행법을 다루는 가이드다. 각 서버별 기동 순서, Let's Encrypt TLS 발급, CI/CD 자동 배포 흐름, 스토어 심사 전 OAuth 콘솔 등록 체크리스트를 설명한다. 상세 인프라 사양 및 환경 변수(GitHub Secrets) 전체 목록은 deploy/environment-reference.md를 참고한다.

관련 문서	용도
environment-reference.md	인프라 사양 및 환경 변수(Secrets) 전체 표 (SSOT)
docs/decisions/002-domain-split-vercel-api.md	도메인 분리 확정
docs/architecture.md	프로필·ddl-auto·레이어
ec2-split-deployment.md	VPC·SG·1→2 EC2 심화
holiday-api-setup.md	공휴일 API 인증키 발급·등록·검증
.claude/rules/deployment.md	에이전트 배포 가드레일

역할별로 분리되어 있습니다.

도메인 구조 (확정)

도메인	호스팅	이 repo
tripfit.online	Vercel (React/Next.js)	프론트 저장소 — EC2에 frontend 컨테이너 없음
api.tripfit.online	EC2 A (Nginx + Spring Boot)	deploy/app/, deploy/nginx/
grafana.tripfit.online	EC2 C (Nginx + Grafana)	deploy/monitoring/ — 운영용, 클라이언트 앱과 무관

Route 53

• tripfit.online → Vercel DNS (CNAME/A, Vercel 대시보드 안내 따름)
• api.tripfit.online → EC2 A Elastic IP (A 레코드)
• grafana.tripfit.online → EC2 C Elastic IP (A 레코드)

프론트 환경 변수 (Vercel)

NEXT_PUBLIC_API_BASE_URL=https://api.tripfit.online

상세: docs/decisions/002-domain-split-vercel-api.md

구조

경로	서버	설명
app/	EC2 A	Nginx(:80/443) + Certbot + Spring Boot API
nginx/	EC2 A	api.tripfit.online 리버스 프록시
mysql/	EC2 B	MySQL 8.0 전용
monitoring/	EC2 C	Loki(:3100) + Grafana(:3000) — A/B 컨테이너 로그 수집·조회
redis/	EC2 D	Redis(:6379) — refresh token 저장소 + 공휴일 캐시, sg-app에서만 접근
../docker-compose.yml	로컬	App build + MySQL (--profile edge 시 API Nginx)

상세 네트워크·SG: ec2-split-deployment.md

빠른 시작

로컬 (MySQL Docker + bootRun)

cp .env.example .env
docker compose up -d              # MySQL만
./gradlew bootRun                 # Spring (localhost:8080, .env 로드)

Spring까지 Docker로 검증할 때만:

docker compose --profile app up -d --build
./scripts/verify-deploy.sh

EC2 B — MySQL

cd deploy/mysql
cp .env.example .env
docker compose up -d

EC2 D — Redis (docs/decisions/010-redis-infra.md)

프로비저닝 완료(2026-08-10) — TP-redis(i-06fb8540484834192), A/B/C와 동일 VPC·서브넷·키페어, t3.micro. Private IP 172.31.38.246, 보안 그룹 TP-redis가 6379를 sg-app(TP-server)에서만 허용. Elastic IP 없음 — App만 사설 IP로 접근하고 외부 도메인이 필요 없는 내부 인프라라 EC2 A/C와 다름.

cd deploy/redis
cp .env.example .env
docker compose up -d

EC2 A — API + HTTPS (Route 53 api.tripfit.online 연결 후)

최초 1회 수동 부트스트랩 전용 — TLS 발급까지 끝내고 나면 이후 배포는 main push → CI/CD가 GitHub Secrets만으로 처리한다 (아래 환경 변수 절). .env는 이 최초 설정과 수동 재배포(ec2-deploy-app.sh 단독 실행) 때만 쓴다.

cd deploy/app
cp .env.example .env
# .env: MYSQL_HOST, GHCR_IMAGE
export SPRING_DATASOURCE_USERNAME=...
export SPRING_DATASOURCE_PASSWORD=...
export CERTBOT_EMAIL=codus5068@naver.com
# private GHCR: export GHCR_PAT=... GHCR_USERNAME=...

../../scripts/setup-api-https.sh

또는 단계별:

../../scripts/ec2-deploy-app.sh          # nginx + certbot + app (임시 self-signed)
../../scripts/init-letsencrypt.sh        # Let's Encrypt 실제 인증서
VERIFY_TLS=true ../../scripts/verify-deploy-app.sh

검증:

curl -fsSI https://api.tripfit.online/health
curl -fsSI https://api.tripfit.online/api/v1/...   # API 구현 후

스택 구성 (deploy/app/docker-compose.yml)

서비스	역할
nginx	api.tripfit.online :80/:443 → app:8080
certbot	LE 발급·12h 갱신 시도
app	Spring Boot (GHCR), 127.0.0.1:8080만 바인딩

cron 갱신 (갱신 시 nginx reload 포함):

0 3 * * * cd /path/to/TripFit-server/deploy/app && /path/to/TripFit-server/scripts/renew-letsencrypt.sh

EC2 A — API (HTTPS 생략, dev만)

../../scripts/setup-api-https.sh --skip-tls

EC2 C — 모니터링 (Loki + Grafana, https://grafana.tripfit.online)

결정 근거: docs/decisions/009-observability-logging.md (Issue #77). A/B와 같은 VPC·서브넷·키페어 재사용, 별도 t3.micro. Elastic IP 보유(EC2 A와 동일 이유 — Grafana URL·SSH가 인스턴스 재시작에 흔들리지 않도록).

cd deploy/monitoring
cp .env.example .env   # GRAFANA_ADMIN_PASSWORD 채우기
docker compose up -d

HTTPS (EC2 A deploy/app와 동일 패턴 — nginx+certbot, Let's Encrypt)

export DEPLOY_DIR=$(pwd)/deploy/monitoring
export CERTBOT_DOMAIN=grafana.tripfit.online
../../scripts/ensure-ssl-certs.sh   # 임시 self-signed (nginx 443 기동용)
docker compose up -d
CERTBOT_EMAIL=codus5068@naver.com ../../scripts/init-letsencrypt.sh

• 스택: nginx(:80/:443) → grafana(내부 127.0.0.1:3000만 바인딩, 공개 노출 없음), certbot(발급·갱신), loki(:3100, A/B가 push하는 대상 — 직접 브라우저 조회 대상 아님).
• Route 53: grafana.tripfit.online A → EC2 C Elastic IP. SG는 22/80/443만 공개, 3100은 A/B SG로만 제한.
• cron 갱신(A와 동일 스크립트, 도메인만 다름): 0 3 * * * DEPLOY_DIR=/home/ubuntu/monitoring CERTBOT_DOMAIN=grafana.tripfit.online /home/ubuntu/scripts/renew-letsencrypt.sh
• A/B 쪽 최초 1회 필수 작업 — Loki가 뜨기 전에 A·B에서 각각 실행해야 docker compose up -d가 driver: loki로 성공한다:

  docker plugin install grafana/loki-docker-driver:latest --alias loki --grant-all-permissions

  (이미 deploy/app/docker-compose.yml, deploy/mysql/docker-compose.yml 상단 주석에도 동일 안내가 있음.)
• 로그 보존: deploy/monitoring/loki-config.yaml의 retention_period(확정 3일, 디스크 6.7GB 제약) + compactor가 자동 삭제 — 별도 cron 불필요.
• 프론트 공유 계정: IP 제한 대신 Grafana Viewer role 읽기 전용 계정을 발급했다(재택·카페 등 IP가 매번 바뀌는 프론트 환경에 IP 화이트리스트는 맞지 않음). 계정 추가 발급은 admin으로 로그인 후 Administration → Users 또는:

  curl -u admin:$GRAFANA_ADMIN_PASSWORD -X POST https://grafana.tripfit.online/api/admin/users \
    -H 'Content-Type: application/json' \
    -d '{"name":"<이름>","login":"<아이디>","email":"<아이디>@tripfit.local","password":"<비밀번호>"}'
  # 기본 org role이 Viewer라 별도 설정 없이도 읽기 전용이지만, 명시적으로 확인하려면:
  curl -u admin:$GRAFANA_ADMIN_PASSWORD -X PATCH https://grafana.tripfit.online/api/org/users/<id> \
    -H 'Content-Type: application/json' -d '{"role":"Viewer"}'

• 기본 대시보드 "TripFit 서비스 로그 개요"(uid: tripfit-overview)가 홈 대시보드로 설정되어 있다 — 에러/경고 건수, nginx 4xx/5xx, app 에러·경고·전체 로그 스트림, nginx 오류 응답 로그. Explore 탭에서 직접 LogQL 조회도 가능.
• CI/CD 대상 아님 — main push 자동 배포는 EC2 A(app)만 다룬다. EC2 C는 위 명령으로 수동 배포·갱신.
• 이 서버는 A/B와 달리 git 체크아웃이 아니라 ~/monitoring·~/scripts에 파일을 직접 올린 상태 — 향후 git 체크아웃으로 전환 권장(009 후속 작업).

환경 변수 관리

애플리케이션 실행 및 배포에 필요한 GitHub Actions Secrets 32개 전체 목록과 기본값, 필수 여부는 deploy/environment-reference.md에서 관리합니다.

주요 관리 원칙

• 자동 주입: main push → CI/CD deploy 단계에서 GitHub Secrets를 SSH 세션 환경 변수로 주입받아 EC2에서 export 후 docker compose up -d를 실행합니다. 한 번 등록해두면 이후 배포는 GitHub Secrets만 갱신하면 되며, EC2에 SSH로 접속해 deploy/app/.env를 생성하거나 수정할 필요가 없습니다.
• Fail-Fast 필수 변수: 필수로 지정된 Secret이 미등록인 채로 push되면 CI/CD 배포 단계가 즉시 실패합니다. 어떤 변수가 필수인지는 environment-reference.md의 표가 SSOT — 목록을 이 문서에 옮겨 적지 않습니다(양쪽에 두면 한쪽만 고쳤을 때 어긋납니다).
• Fail-Safe 호스트 변수: 모니터링(EC2 C)·Redis(EC2 D) 호스트 변수는 Secret 미설정 시에도 compose 기본값으로 컨테이너가 정상 기동되도록 처리돼 있습니다. 사설 IP가 바뀌면 GitHub Secret과 compose 기본값을 함께 갱신해야 합니다 — 변수명·현재 기본값은 environment-reference.md 참조.
• FRONTEND_IMAGE 사용 금지: FRONTEND_IMAGE 사용하지 않음 — 프론트는 Vercel. EC2에 프론트엔드 컨테이너가 없으므로 변수를 사용하거나 추가하지 않습니다.
• 수동 배포 및 로컬: scripts/ec2-deploy-app.sh 수동 실행이나 로컬 docker compose 시에는 .env 또는 export로 값을 전달합니다 (deploy/app/.env.example 및 루트 .env 참고).
• 전체 환경 변수 표 및 상세 설명: deploy/environment-reference.md 참조

스토어 제출 전 OAuth 콘솔 설정 체크리스트

위 GOOGLE_CLIENT_ID류·KAKAO_ADMIN_KEY는 env(GitHub Secrets)에 값만 등록하면 되지만, 각 소셜 로그인 콘솔(Google Cloud Console·Apple Developer·Kakao Developers 등) 쪽 설정은 별도로 채워야 실제 로그인이 동작한다. 코드·검증 로직(GoogleTokenVerifier·AppleTokenVerifier·KakaoTokenVerifier·OAuthProperties)은 이미 완료된 상태 — 아래는 콘솔 담당자가 콘솔 화면에서 직접 등록하면 되는 항목뿐이다.

미등록 상태로는 redirect_uri_mismatch·DEVELOPER_ERROR 등으로 로그인 자체가 실패하므로 스토어 심사 제출 전 반드시 확인. (과거 GitHub Issue #62로 추적하던 체크리스트였으나 2026-08-02부로 이슈를 닫고 이 문서를 SSOT로 통합했다 — 아래가 최신 상태.)

담당 구분:

담당	필요한 것
백엔드	코드 변경 없음 — 각 콘솔에 실제 값 입력만(계정 접근 권한 필요)
프론트	최종 서비스 도메인·콜백 라우트(리다이렉션 URI로 등록될 경로) 확정해서 전달 — Google/Kakao Redirect URI·네이티브 앱 키·패키지명은 이미 코드 확인으로 전달 완료
빌드 환경 담당자	Android 디버그·릴리즈 keystore의 SHA-1(Google)·키 해시(Kakao) 추출 — 리포에 keystore가 없어 콘솔 담당자가 대신할 수 없음
Apple/Google 계정 담당자	App Store ID는 App Store Connect 앱 등록 완료 후에만 발급 — 게시 담당자가 값 전달

Google Cloud Console

기존 로그인용 GCP 프로젝트의 APIs & Services → Credentials에서 아래 3개 Client(이미 발급돼 있음)를 각각 연다.

Client 타입	대응 env	지금 등록할 것	시점
Web application	GOOGLE_CLIENT_ID	승인된 자바스크립트 원본(https://tripfit.online) + 승인된 리다이렉션 URI(프론트 콜백 경로)	프론트 최종 도메인·콜백 라우트 확정 후
Android	GOOGLE_CLIENT_ID_ANDROID	패키지명 com.tripfit.app + SHA-1 인증서 지문(디버그·릴리즈 각각)	SHA-1 확보 즉시
iOS	GOOGLE_CLIENT_ID_IOS	번들 ID com.tripfit.app + App Store ID(선택 필드)	앱 App Store 게시 후

SHA-1 확보 방법 — 리포에 keystore가 없어 콘솔 담당자가 직접 뽑을 수 없다. 빌드 환경(Android Studio/CI) 담당자에게 아래 명령 실행을 요청:

keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android | grep SHA1

릴리즈 keystore는 별도 보유자가 동일 명령으로 추출(Google Play App Signing을 쓰면 Play Console의 "앱 무결성 → 앱 서명" 메뉴에서도 확인 가능).

값 일치 확인: apps/app(네이티브 앱)의 GOOGLE_WEB_CLIENT_ID, apps/web의 NEXT_PUBLIC_GOOGLE_CLIENT_ID, 백엔드 GOOGLE_CLIENT_ID 세 값이 전부 같은 Web Client ID를 가리켜야 한다 — 하나라도 다르면 그 경로만 aud mismatch로 로그인이 실패한다.

Calendar 전용 Client(GOOGLE_CALENDAR_CLIENT_ID) 발급은 지금 안 해도 된다 — Calendar FE 착수 시점에 google-calendar-client-id-separation.md "GCP 콘솔 가이드" 절 참고.

Kakao Developers Console

앱 대시보드(developers.kakao.com → 내 애플리케이션 → 해당 앱)에서:

메뉴	등록할 것
앱 설정 → 플랫폼	Android 패키지명 com.tripfit.app + 키 해시(아래 명령), iOS 번들 ID com.tripfit.app, 네이티브 앱 키가 6a686bacf5c3efba84a1cc8d0e655cd5와 일치하는지 확인
카카오 로그인 → 활성화 설정	ON
카카오 로그인 → Redirect URI	https://tripfit.online/auth/kakao/callback(운영) + http://localhost:3000/auth/kakao/callback(로컬) — 환경 B(모바일 웹/데스크톱 브라우저) JS SDK 리다이렉트 플로우용
카카오 로그인 → 동의항목	닉네임·프로필 사진 활성화(선택 동의로 충분), 이메일은 필요 시 활성화 — 꺼져 있으면 백엔드는 해당 필드를 null로 받음(로그인 자체는 안 깨짐)
보안 → Admin Key	이미 발급 완료 상태 — KAKAO_ADMIN_KEY GitHub Secret에 등록돼 있는지만 재확인

키 해시 확보 방법 (Google SHA-1과 같은 keystore 필요):

keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore -storepass android | openssl sha1 -binary | openssl base64

릴리즈용은 릴리즈 keystore로 동일 명령을 실행해 별도 등록.

CI/CD

.github/workflows/ci-cd.yml — main push → GHCR push → EC2 A deploy (app + nginx + certbot) deploy 시 위 GitHub Secrets 전부가 app 컨테이너에 자동 주입된다 — EC2 쪽 .env 유무와 무관하게 동작한다. EC2 B(MySQL)·EC2 C(모니터링)는 이 파이프라인 밖 — 최초 설정·재배포 모두 수동(deploy/mysql/, deploy/monitoring/ 절 참고).

검증 스크립트

스크립트	사용 시점
scripts/verify-deploy.sh	로컬 compose
scripts/setup-api-https.sh	배포 + LE 발급 일괄 (권장)
scripts/ec2-deploy-app.sh	pull + up (임시 self-signed)
scripts/init-letsencrypt.sh	LE 최초 발급 (api.tripfit.online)
scripts/renew-letsencrypt.sh	갱신 + nginx reload (cron)
scripts/verify-deploy-app.sh	EC2 A 검증 (VERIFY_TLS=true)