Google Cloud에 배포

초보자 연습

전제 조건: 로컬에서 작동하는 앱, 인터넷에서 접근 가능한 실제 데이터베이스(데이터베이스 설정), 그리고 출시하는 기능의 공급자 계정. Google 계정이 필요합니다. 가벼운 사용은 무료 등급 내에 있지만 결제 설정에서는 카드를 요구합니다.

용어 정리: 컨테이너 이미지는 어떤 호스트에서도 실행할 수 있는 앱의 패키징된 복사본입니다. Artifact Registry는 Google의 이미지 저장소입니다. Cloud Build는 Google의 머신에서 이미지를 빌드합니다—로컬 Docker가 필요 없습니다. Cloud Run은 이미지를 HTTPS 서비스로 실행하고 스케일링합니다. Secret Manager는 비밀번호와 키를 보관합니다. 리비전은 서비스의 배포된 버전 하나입니다.

만들 것: Google Cloud 프로젝트, 이미지를 보관하는 Artifact Registry 리포지토리, HTTPS로 앱을 제공하는 Cloud Run 서비스, Secret Manager의 시크릿, 그리고 관리형 Postgres. 킷의 루트 Dockerfile은 이미 포트 8080에서 수신 대기하는 독립형 Next.js 서버를 생성합니다—정확히 Cloud Run이 기대하는 것입니다.

솔직한 비용 참고: Cloud Run의 무료 등급은 가벼운 트래픽을 커버하지만, Google의 관리형 Postgres인 Cloud SQL에는 무료 등급이 없습니다. Supabase 또는 Neon 무료 등급 데이터베이스가 가장 저렴한 시작 방법입니다. 이 가이드는 그 경로를 사용합니다. 실험하기 전에 Billing → Budgets & alerts(결제 → 예산 및 알림)에서 예산 알림 추가를 고려하세요.

• 데이터베이스 설정
• 먼저 OAuth 계정 만들기

계정 만들기 및 CLI 설치

1. console.cloud.google.com을 열고 Google 계정으로 로그인한 후 약관에 동의합니다.

2. 요청받으면 결제를 연결합니다: Billing → Link a billing account → Create billing account(결제 → 결제 계정 연결 → 결제 계정 만들기). 계정 활성화에는 카드가 필요합니다. 평가판 크레딧이 초기 실험을 커버합니다.

3. 프로젝트 드롭다운 → New Project(새 프로젝트)를 클릭하고 이름을 지정한 후 Create(만들기)—또는 Google 로그인용으로 만든 프로젝트를 재사용합니다. 프로젝트는 하나면 됩니다.

4. cloud.google.com/sdk에서 Google Cloud CLI를 설치합니다. 운영 체제용 설치 프로그램을 다운로드하여 완료한 후 새 터미널을 열어 gcloud 명령을 사용할 수 있게 합니다.

5. 아래 두 명령을 실행합니다. 첫 번째는 브라우저를 열어 CLI를 인증하고, 두 번째는 프로젝트를 선택합니다—콘솔 대시보드에 표시된 프로젝트 ID를 사용하세요. 이름과 항상 같지는 않습니다.

예상 결과: gcloud config list에 계정과 프로젝트가 표시됩니다. gcloud가 인식되지 않으면 터미널을 다시 열거나 먼저 설치 프로그램을 완료하세요.

gcloud auth login
gcloud config set project YOUR_PROJECT_ID

프로덕션 데이터베이스 만들기

초보자 경로—Google 외부의 관리형 Postgres. supabase.com에서: New project(새 프로젝트)→ 이름, 데이터베이스 비밀번호, 리전 선택 → 프로비저닝 대기 → Project Settings → Database(프로젝트 설정 → 데이터베이스). Supabase는 두 가지 연결 문자열을 제공합니다: 포트 5432의 세션 풀러 / 직접 연결과 포트 6543의 트랜잭션 풀러입니다—5432 문자열은 마이그레이션과 장기 클라이언트용이고, 6543 문자열은 서버리스 앱용입니다. neon.tech에서는: New project → 표시되는 연결 문자열 복사. 둘 다 됩니다. 비밀번호 부분은 그대로 유지하세요.

직접/세션 문자열을 루트 .env의 DATABASE_URL에 넣습니다—마이그레이션 도구는 루트 파일을 읽고 세션 연결이 필요합니다—그리고 로컬 개발 서버용으로 apps/web/.env.local에도 넣습니다. 그런 다음 리포지토리 루트에서 마이그레이트 명령을 한 번 실행하여 새 데이터베이스에 킷의 테이블을 만듭니다. 배포된 앱이 사용하는 DATABASE_URL 시크릿은 대신 풀링된 6543 문자열일 수 있습니다.

Google 네이티브 대안은 같은 프로젝트 내의 관리형 Postgres인 Cloud SQL입니다. 무료 등급이 없고 비공개 IP 연결에는 VPC 커넥터가 필요합니다—시작점이 아니라 나중의 업그레이드로 취급하세요.

# DATABASE_URL=<the direct/session Postgres string, port 5432> in .env + apps/web/.env.local, then:
corepack pnpm --filter @supastack/db db:migrate

서비스 활성화 및 이미지 푸시

아래 명령을 리포지토리 루트에서 실행합니다. 이 배포가 사용하는 네 개의 Google 서비스를 활성화하고, Artifact Registry에 Docker 리포지토리를 만들고, 리포지토리를 Cloud Build에 제출합니다—루트 Dockerfile을 원격으로 빌드하므로 Docker Desktop이 필요하지 않습니다.

YOUR_PROJECT_ID를 교체하고 리전 하나를 선택해—아래에서는 us-central1—리포지토리와 서비스 모두에 재사용합니다. 예상 결과: 빌드 로그가 몇 분간 스트리밍되고 DONE / STATUS: SUCCESS로 끝납니다. 그러면 콘솔의 Artifact Registry → supastack → web에 이미지가 나타납니다.

gcloud services enable run.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com secretmanager.googleapis.com

gcloud artifacts repositories create supastack --repository-format=docker --location=us-central1

gcloud builds submit --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/supastack/web:latest

Secret Manager에 시크릿 저장

시크릿은 절대 --set-env-vars나 이미지에 넣어서는 안 됩니다—둘 다 평문으로 저장되어 서비스 구성을 읽을 수 있는 사람이면 누구에게나 보입니다. Secret Manager는 암호화하여 보관하고 런타임에 주입합니다.

1. 콘솔에서 Security → Secret Manager → Create Secret(보안 → Secret Manager → 시크릿 만들기)을 엽니다.

2. 전체 Postgres 연결 문자열로 DATABASE_URL을 만들고—앱에는 풀링된 서버리스 문자열이면 됩니다—AUTH_SECRET에는 최소 32자의 임의 문자(openssl rand -hex 32로 생성 가능), CREDENTIAL_ENCRYPTION_KEY에는 Base64 인코딩된 32바이트 키(openssl rand -base64 32)를 설정합니다. 이는 워크스페이스가 앱에 저장하는 공급자 키를 암호화합니다.

3. 활성화한 공급자당 하나의 시크릿을 만듭니다—예를 들어 STRIPE_SECRET_KEY와 STRIPE_WEBHOOK_SECRET, RESEND_API_KEY, GOOGLE_CLIENT_SECRET, GITHUB_CLIENT_SECRET. EMAIL_PROVIDER=resend 같은 비밀 시크릿이 아닌 설정은 시크릿이 아니라 일반 환경 변수로 둡니다.

서비스가 처음으로 시크릿을 참조할 때 런타임 서비스 계정에 읽기 권한이 필요합니다—콘솔의 서비스 편집기에서 시크릿을 연결하면 Google이 해당 권한을 자동으로 제안합니다. CLI에서는 배포 오류가 부여해야 할 누락된 Secret Manager 역할을 지목합니다.

# Secrets to create in Secret Manager:
DATABASE_URL     # Postgres connection string — the pooled serverless string is fine
AUTH_SECRET      # openssl rand -hex 32
CREDENTIAL_ENCRYPTION_KEY   # openssl rand -base64 32

# plus one per enabled provider, e.g.:
STRIPE_SECRET_KEY
STRIPE_WEBHOOK_SECRET
RESEND_API_KEY
GOOGLE_CLIENT_SECRET
GITHUB_CLIENT_SECRET

Cloud Run 서비스 배포

콘솔 경로: Cloud Run → Create service(서비스 만들기)→ Deploy one revision from an existing container image(기존 컨테이너 이미지에서 리비전 하나 배포)→ 푸시된 …/supastack/web:latest 이미지 선택 → 같은 리전 선택 → Authentication(인증)에서 Allow unauthenticated invocations(인증되지 않은 호출 허용) 선택(공개 앱이므로)→ Create.

아래 CLI 동등 명령은 같은 단계에서 환경 연결을 추가합니다. 평문 구성은 --set-env-vars에 넣고, 시크릿은 --set-secrets에서 Secret Manager 이름으로 참조합니다. 공급자 플래그(EMAIL_PROVIDER, BILLING_PROVIDER, AI_PROVIDER, JOB_PROVIDER)는 APP_URL과 함께 일반 env 변수로 추가합니다.

APP_ENV=production은 필수입니다—이것이 없으면 앱이 local 모드로 부팅됩니다. 프로덕션 구성 검증이 건너뛰어지고, 보안 쿠키 접두사가 꺼진 채로, 개발 전용 /mail-preview 페이지가 공개적으로 접근 가능한 상태로 남습니다(EMAIL_PROVIDER=local일 때 로컬 이메일 발신함이 유출됩니다). 그러면 프로덕션은 부팅 시 네 가지 값을 추가로 요구합니다. EXPO_PUBLIC_API_URL은 모바일 앱이 API에 도달하는 공개 https URL입니다—서비스 URL로 설정합니다(웹 전용 배포에서는 APP_URL과 동일). EXPO_PUBLIC_APP_SCHEME은 모바일 딥링크 스킴입니다—모바일 앱을 출시하지 않으면 supastack 같은 유효한 값이면 됩니다. MOBILE_ALLOWED_ORIGINS는 서버가 신뢰하는 정확한 https 원본의 쉼표 구분 목록입니다—앱 URL이 적절한 시작점이며 와일드카드는 거부됩니다. CREDENTIAL_ENCRYPTION_KEY는 저장된 공급자 자격 증명을 암호화하고 Secret Manager에 둡니다.

Cloud Run은 첫 배포에서 https://….run.app URL을 할당하고, 인증 콜백과 링크가 작동하려면 앱의 APP_URL이 실제 공개 URL과 같아야 합니다. 따라서 먼저 자리 표시자로 한 번 배포하고, 서비스 페이지에서 *.run.app URL을 복사한 다음, APP_URL—및 그에 맞는 EXPO_PUBLIC_API_URL / MOBILE_ALLOWED_ORIGINS 값—을 그 URL로 설정하여 서비스를 업데이트합니다(콘솔: Edit & deploy new revision(새 리비전 편집 및 배포), 또는 명령 재실행). 컨테이너 포트는 8080으로 유지됩니다—Cloud Run 기본값이 이미 Dockerfile의 PORT와 일치합니다.

gcloud run deploy supastack --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/supastack/web:latest --region us-central1 --allow-unauthenticated --set-env-vars "APP_ENV=production,APP_URL=https://YOUR_SERVICE_URL,EXPO_PUBLIC_API_URL=https://YOUR_SERVICE_URL,EXPO_PUBLIC_APP_SCHEME=supastack,MOBILE_ALLOWED_ORIGINS=https://YOUR_SERVICE_URL" --set-secrets "DATABASE_URL=DATABASE_URL:latest,AUTH_SECRET=AUTH_SECRET:latest,CREDENTIAL_ENCRYPTION_KEY=CREDENTIAL_ENCRYPTION_KEY:latest"

자체 도메인 매핑(선택 사항)

테스트 중에는 건너뛰세요—*.run.app URL이 이미 HTTPS를 제공합니다. 준비가 되면: Cloud Run → 서비스 → Custom Domains / Domain Mappings(사용자 지정 도메인 / 도메인 매핑)→ Add mapping(매핑 추가)→ 서비스를 선택하고 도메인을 입력합니다.

요청받으면 도메인 소유권을 확인하고(Google이 안내합니다), 등록기관에서 매핑 화면에 나열된 DNS 레코드를 만듭니다. 관리형 HTTPS 인증서는 레코드가 전파된 후 자동으로 발급됩니다—보통 몇 분, 최대 하루입니다.

도메인이 트래픽을 제공하면 APP_URL을 https://yourdomain.com으로 업데이트하고 일치하는 OAuth 리디렉션 URI(https://yourdomain.com/api/auth/callback/…)를 등록합니다—로그인 가이드가 위치를 다룹니다.

배포 확인

https://YOUR_SERVICE_URL/api/health를 엽니다—ok가 예상됩니다. 그런 다음 앱을 처음부터 끝까지 시험합니다. URL을 열고, 가입하고, 이메일 코드를 요청하고, 받은 편지함에 도달하는지 확인합니다(EMAIL_PROVIDER=resend, RESEND_API_KEY, 인증된 발신자가 필요합니다—로컬 어댑터는 실제 받은 편지함에 도달하지 않습니다). 로그인하고 활성화한 기능 하나를 사용합니다.

Cloud Run → 서비스 → Logs(로그)에 요청 및 오류 출력이 표시됩니다. Revisions(리비전) 탭은 배포가 잘못되면 이전 리비전으로 원클릭 롤백을 제공합니다.

모바일 및 데스크톱 클라이언트는 이 HTTPS 백엔드를 가리켜야 합니다. Expo에서는 apps/mobile/.env.local의 EXPO_PUBLIC_API_URL, 데스크톱 셸에서는 SUPASTACK_APP_URL입니다.

• 모바일 계정 만들기
• 전체 배포 체크리스트 실행