Google Cloud にデプロイ

初心者向けのウォークスルー

前提条件:ローカルで動作するアプリ、インターネットから到達できる実際のデータベース(データベースのセットアップ)、そしてリリースする機能のプロバイダーアカウント。Google アカウントが必要です。軽い利用は無料枠内に収まりますが、請求設定ではカードの登録を求められます。

用語メモ:コンテナイメージは、どのホストでも実行できるアプリのパッケージ済みコピーです。Artifact Registry は Google のイメージ保管庫です。Cloud Build は Google のマシン上でイメージをビルドします——ローカルの Docker は不要です。Cloud Run はイメージを HTTPS サービスとして実行し、スケールします。Secret Manager はパスワードとキーを保持します。リビジョンはサービスのデプロイ済みバージョン 1 つを指します。

構築するもの: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 サインイン用に作成したプロジェクトを再利用します。プロジェクトは 1 つで構いません。

4. cloud.google.com/sdk から Google Cloud CLI をインストールします。OS 用のインストーラーをダウンロードして完了したら、新しいターミナルを開いて gcloud コマンドが使えるようにします。

5. 以下の 2 つのコマンドを実行します。最初のコマンドはブラウザを開いて CLI を認証し、2 つ目はプロジェクトを選択します——コンソールダッシュボードに表示されるプロジェクト 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 は 2 種類の接続文字列を提供します:ポート 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

サービスを有効化してイメージをプッシュする

以下のコマンドをリポジトリルートから実行します。このデプロイが使う 4 つの Google サービスを有効化し、Artifact Registry に Docker リポジトリを作成し、リポジトリを Cloud Build に送信します——ルートの Dockerfile をリモートでビルドするため、Docker Desktop は不要です。

YOUR_PROJECT_ID を置き換え、リージョンを 1 つ選び——以下では 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. 有効にしたプロバイダーごとに 1 つのシークレットを作成します——例えば 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(既存のコンテナイメージから 1 リビジョンをデプロイ)→ プッシュした …/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 と一緒に通常の環境変数として追加します。

APP_ENV=production は必須です——これがないとアプリは local モードで起動します。本番設定の検証がスキップされ、セキュアクッキープレフィックスが無効のまま、開発専用の /mail-preview ページが公開されたままになります(EMAIL_PROVIDER=local の場合、ローカルのメール送信トレイが漏洩します)。本番では起動時にさらに 4 つの値が必要です。EXPO_PUBLIC_API_URL はモバイルアプリが API に到達するための公開 https URL です——サービス URL に設定します(Web のみのデプロイでは 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 証明書はレコードが伝播した後に自動で発行されます——通常数分、最長で 1 日です。

ドメインがトラフィックを配信し始めたら、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、検証済み送信者が必要です——ローカルアダプターは実際の受信トレイには届きません)。サインインして、有効にした機能を 1 つ使います。

Cloud Run → サービス → Logs(ログ)にリクエストとエラーの出力が表示されます。Revisions(リビジョン)タブでは、デプロイが失敗した場合に前のリビジョンへワンクリックでロールバックできます。

モバイルとデスクトップのクライアントはこの HTTPS バックエンドを指す必要があります。Expo では apps/mobile/.env.local の EXPO_PUBLIC_API_URL、デスクトップシェルでは SUPASTACK_APP_URL です。

• モバイルアカウントを作成する
• 完全なデプロイチェックリストを実行