cloudrun-gcs-litestream-sample

Quick Start

gcloud auth application-default login
gcloud config set project <YOUR_PROJECT_ID>
gcloud storage buckets create gs://<YOUR_UNIQUE_STATE_BUCKET_NAME> \
  --project=<YOUR_PROJECT_ID> \
  --location=asia-northeast1

cd terraform
# 値を自分のプロジェクトに合わせて編集
cp terraform.tfvars.example terraform.tfvars
# 値を自分のプロジェクトに合わせて編集
cp backend.hcl.example backend.hcl

terraform init -backend-config=backend.hcl
terraform apply

Terraform で GCP に接続する（初期手順）

前提

• Terraform（1.6 以上）
• Google Cloud CLI（gcloud）
• GCP プロジェクト（課金有効）
• Terraform state 用の GCS バケットが別途存在すること
  このスタックの state を保存するバケットを、この Terraform より先に手動または別手順で用意する（初回 apply でバケット自身を作ると、state の置き場所と矛盾しやすいため）。

認証（ローカル）

Application Default Credentials を使う。

gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID

CI や本番の認証は Workload Identity Federation 等、環境に合わせて別途設定する。

State 用バケット（概要）

• バケット名・リージョン・権限（Terraform を実行する主体が storage.objects 相当で読み書きできること）は環境ごとに決める。
• 手順の例: バケットの作成（コンソールまたは gcloud storage buckets create）。

gcloud storage buckets create gs://YOUR_UNIQUE_STATE_BUCKET_NAME \
  --project=YOUR_PROJECT_ID \
  --location=asia-northeast1

Terraform の設定ファイル

cd terraform
cp terraform.tfvars.example terraform.tfvars
cp backend.hcl.example backend.hcl

terraform.tfvars と backend.hcl を編集する。

• terraform.tfvars: project_id、region、name（スタック識別子。Cloud Run・イメージは name-api / name-frontend）、default_labels、artifact_registry（リポジトリ ID など）、任意で services（backend / frontend のスケール・タグ等。image_tag 省略時はソースハッシュ由来タグ）、cloud_run_empty_dir_size_limit など
• backend.hcl: state を置く bucket と prefix（環境やプロジェクトキーで区切るとよい）

init・検証

terraform init -backend-config=backend.hcl
terraform validate
terraform plan

plan が権限エラーなく完了し、google_project の data source が評価できれば接続はできている。

補足

• terraform.tfvars と backend.hcl は .gitignore によりコミット対象外（実値の混入防止）。
• プロバイダのバージョン固定は terraform/.terraform.lock.hcl をリポジトリに含める。
• name のデフォルトは app（省略時は Cloud Run が app-api / app-frontend、Litestream 用 GCS が ${project_id}-app-litestream など。terraform.tfvars の name で任意に変更可）。

Cloud Run + GCS + Litestream へのデプロイ

• API（backend）: コンテナに Litestream v0.5.10 と Rust バイナリを同梱し、SQLite（WAL）を GCS にレプリケートする。
• フロントエンド: frontend/ を Docker（Node でビルド → nginx で静的配信）し、ビルド時に API サービスの Cloud Run URL を VITE_API_URL として埋め込む。

terraform apply 時に ローカルの Docker で backend/ と frontend/ を順にビルドし、Artifact Registry へプッシュしてから Cloud Run を更新する（API サービス作成後にフロントのイメージビルドが走る）。

追加前提

• Docker（docker build / docker push が使えること）
• artifact_registry.format は DOCKER（null_resource によるビルド・プッシュの前提）
• 初回またはリージョン変更後に、Artifact Registry への認証:

gcloud auth configure-docker ${REGION}-docker.pkg.dev

（REGION は terraform.tfvars の region と一致させる。例: asia-northeast1-docker.pkg.dev）

apply

cd terraform
terraform init -backend-config=backend.hcl
terraform apply

• terraform/docker.tf 内の null_resource.docker_build_push（backend/）と null_resource.docker_build_push_frontend（frontend/）がソース指紋で変更を検知し、変更時のみ docker build / docker push を実行する。
• services.*.image_tag を省略した場合、イメージタグはソース指紋由来の短いハッシュになる。固定タグを明示した場合でも、Cloud Run revision template には deploy_hash ラベルを載せるため、新しいリビジョンが切られる。
• デプロイ後、terraform output cloud_run_url（API）と terraform output frontend_cloud_run_url（UI）で URL を確認できる（いずれも未認証で HTTPS 公開）。

デプロイ後の curl 例

Cloud Run のベース URL をシェル変数に入れてから叩く（terraform ディレクトリで実行する）。

cd terraform
BASE_URL=$(terraform output -raw cloud_run_url)

操作	コマンド
作成	curl -sS "$BASE_URL/tasks" -X POST -H 'Content-Type: application/json' --data '{ "title": "aaa" }'
一覧	curl -sS "$BASE_URL/tasks"
1 件	curl -sS "$BASE_URL/tasks/1"
更新	curl -sS "$BASE_URL/tasks/1" -X PATCH -H 'Content-Type: application/json' --data '{ "title": "updated", "completed": true }'
削除	curl -sS "$BASE_URL/tasks/1" -X DELETE

BASE_URL を使わず、出力された https://....run.app をそのまま http://localhost:8080 の代わりに置き換えてもよい。

フロントの URL は terraform output -raw frontend_cloud_run_url。ブラウザで開くと、ビルド時に埋め込んだ API URL へフェッチする（CORS は API 側で許可）。

ローカルと本番の DB パス

• ローカル: 環境変数未設定時は tasks.db（カレントディレクトリ）。
• Cloud Run: DATABASE_PATH=/backend/data/tasks.db、メモリ上の empty_dir に SQLite を置き、停止時は Litestream が GCS に複製済みのため、次回起動時にリストアされる。

ローカルで Task API を起動する

Rust と cargo が使えること。

cd backend
cargo run

サーバーは http://localhost:8080 で待ち受け、データは backend/tasks.db に保存される。別ターミナルで curl する。

curl の例

操作	コマンド
作成	curl http://localhost:8080/tasks -X POST -H 'Content-Type: application/json' --data '{ "title": "aaa" }'
一覧	curl http://localhost:8080/tasks
1 件	curl http://localhost:8080/tasks/1
更新	curl http://localhost:8080/tasks/1 -X PATCH -H 'Content-Type: application/json' --data '{ "title": "updated", "completed": true }'
削除	curl http://localhost:8080/tasks/1 -X DELETE

詳細は CLAUDE.md の「アプリ（Rust API）」を参照。

ローカルでフロントエンド（React）を起動する

Node.js（npm 付き）が使えること。

cd frontend
npm install
npm run dev

別ターミナルで API を cd backend && cargo run しておく。既定の API URL は http://localhost:8080（VITE_API_URL で変更可）。詳細は CLAUDE.md の「フロントエンド（React）」を参照。