Deployment (Render · Vercel · Branch policy)

Overview

Branch 정책 (Git Flow 단순화)

• main — production (자동 배포). 직 push 금지.
• develop — default 통합 브랜치. 모든 PR base.
• feature/* — 작업 단위. SPEC 당 1 브랜치.

머지 정책:

Branch protection (main · develop):

• Build CI 통과 필수
• 1 review approval 필수 (Copilot review 포함 자체 평가)
• 직 push 금지

main → release 자동화

develop → main 머지 후 무조건 release 생성 (memory feedback_release_on_main_merge):

gh release create vX.Y.Z --title "vX.Y.Z" --notes "포함 SPEC: #NNN · #MMM ..." --target main

SemVer:

• 사용자 기능 추가 (인증·HQ 등록 등) — minor (0.1.0 · 0.2.0 …)
• 디자인 시스템 · 인프라 — patch
• breaking change — major (1.0.0 = 베타 출시)

Vercel 설정 (apps/admin)

Vercel monorepo + sub-app pattern:

• Root Directory 는 sub-app 폴더 (apps/admin).
• 그 폴더 안에도 .nvmrc + engines.node + packageManager ([[feedback-9]]).
• Vercel 이 root engines / .nvmrc 만 보고 sub-app 의 minor 가 안 맞으면 engine-strict fail.

Vercel 설정 (apps/space) — 신설 필요

매장 클라이언트(본사+점장 한 앱). admin 과 다른 origin(space.linkmusic.io)이므로 별도 Vercel project.

env vars (server-side only):

• BACKEND_BASE_URL — backend API base (prod: https://linkmusic-msa-space-was.onrender.com)
• SESSION_PASSWORD — iron-session 암호화 키 (≥32 bytes random). apps/admin 과 별개 값으로 둘 것 (세션 cookie 네임스페이스 분리 — lm_space_session). 누락 시 부팅 거부.

Vercel 설정 (apps/docs) — 신설 필요

도메인:

• 초기 — Vercel preview URL
• 후속 — docs.linkmusic.io 또는 linkmusic-docs.vercel.app

Render 설정 (backend)

• Service type: Web Service
• Runtime: Docker (또는 native Java)
• Auto-deploy: main push
• Health check: /actuator/health
• env vars (prod):
  • JWT_SECRET (≥64 chars, base64)
  • DATABASE_URL (Render PG 자동 주입)
  • SPRING_PROFILES_ACTIVE=render
  • STORAGE_AZURE_CONNECTION_STRING (#041 — 음원 blob 스토리지. 선택: 미설정 시 Local 어댑터로 부팅·blob 미저장. production 실사용 전 필수)
  • STORAGE_AZURE_CONTAINER (#041 — 기본 music)
  • STORAGE_AZURE_PREFIX (#041 — 기본 music)
  • … (env var 추가 시 main 머지 전 사용자 안내 의무 — [[memory: announce_new_env_vars]])

Azure Blob 스토리지 · 스토리지 추상화 (#041)

음원 파일 업로드(#041)는 backend StoragePort 추상화로 저장소를 분리한다 — Local 어댑터(기본) 와 AzureBlobStorageAdapter. Azure 어댑터는 storage.azure.connection-string(env STORAGE_AZURE_CONNECTION_STRING)이 주입됐을 때만 @ConditionalOnProperty 로 활성화되고, 없으면 Local 어댑터로 부팅(blob 미저장)한다. 따라서 Azure 자격증명을 구축·제공하기 전에도 backend 가 부팅·동작한다(blob 저장만 비활성). production 실사용 전 connection-string 주입이 필수다.

main 머지 전 안내 의무([[memory: announce_new_env_vars]]) — Azure connection-string 은 production 시크릿. 사용자가 구축 후 제공한다. 미설정 시 Local 어댑터로 부팅돼 deploy 자체는 실패하지 않으나 blob 이 저장되지 않는다. 업로드 흐름·태그 재기록은 Music Upload.

env var 정책

• 클라이언트 노출은 NEXT_PUBLIC_* 만.
• .env* 파일은 편집/커밋 금지.
• production 시크릿 (JWT_SECRET · SESSION_PASSWORD · API key) — 추가 시 main 머지 전 사용자에게 명시적 안내. 누락 시 deploy fail.
• .env.example 만 commit.

CI (GitHub Actions)

• .github/workflows/ci.yml:
  • Trigger: push to develop/main + PR
  • matrix: node 20.20.2
  • steps: pnpm install --frozen-lockfile → pnpm -r lint typecheck test build
• .github/workflows/e2e.yml: 풀스택 E2E harness(docker compose pg→backend→frontend + Playwright happy-path). develop 대상 PR·수동 dispatch에서만 동작하며 현재 논블로킹(required status check 미등록, 안정화 후 승격 검토). standalone 빌드는 BUILD_STANDALONE=1(Dockerfile.e2e)로 E2E 도커 이미지에서만 켜진다 — 기본/Vercel 빌드 무영향.
• branch protection 에 status check 등록

Pre-deploy 체크리스트 (memory local_verify_before_push)

push 전:

• pnpm -r typecheck 통과
• pnpm -r lint 통과
• pnpm -r test 통과
• pnpm -r build 통과 (실제 배포 시 발생 가능한 실수 사전 차단)
• 새 env var 있다면 사용자 안내 노트 작성
• cross-cutting grep — 같은 helper 가 다른 호출처에 적용 필요한지 ([[feedback-16]])

Roadmap

• staging 환경 분리 — develop → preview · main → production (현재 dev 가 develop 통합 역할)
• env var 자동 비교 (CI 가 .env.example 과 Render env 비교)
• Sentry · Vercel Analytics 도입

References

• 워크스페이스 CLAUDE.md (Git 전략)
• .github/workflows/ci.yml
• linkmusic-frontend-space/apps/admin/.nvmrc
• memory feedback_* (workflow 전반)