🆕 Smalruby 独自 — Smalruby のバックエンド(
infra/の CDK プロジェクト)と GUI ビルドの、stg と prod の違いの一覧
ブランチプレビューは stg の API を見る(本番のデータをテストに使わないため、また ?devlogin=<DEV_BYPASS_TOKEN> でログインを省いて自動テストできるようにするため)。目標は 「stg と prod は設定値以外まったく同じ」。この文書は、その目標から見て今の違いがどこにあるかをまとめ、意図した違い(設定値) と 直すべき違い を分ける。
- 対象:
infra/の 6 プロジェクト(smalruby-mesh-v2 / smalruby-rubytee-relay / smalruby-classroom / smalruby-api / smalruby-bug-report / smalruby-admin)と、GUI のビルド(.github/workflows/ci-cd.ymlのbuild-and-deploy、packages/scratch-gui/webpack.config.js)。 .env.*は gitignore されているので、main checkout にあるinfra/<project>/.env.stgと.env.prod(mesh-v2 は.env.production)を比べた。キーの有無と、秘密の値は同じ値かどうかだけを比べた(値そのものはここに書かない)。Deploy Infraが使う repo Secrets(INFRA_STG_DOTENV_*/ EnvironmentprodのINFRA_PROD_DOTENV_*)の中身は読めないので、ローカルの.env.*と同じ内容だと仮定している。- 秘密の値(トークン・キー・クライアント ID の実値)は書かない。公開されているホスト名は書く。
- インフラの違いの大半は意図した違い。stage ごとのリソース名(prod は接尾辞なし)、カスタムドメイン(
stg.付き)、ログの保持期間、スロットリング、データ保持(RETAIN / PITR)、DEV_BYPASS_TOKEN(stg だけ)、admin の JWT authorizer(prod だけ)。 - プレビューを stg に向けるための前提はそろっている: stg の API の CORS は
https://preview.smalruby.appを許可し(非 prod ではコードが足す)、stg 向けの GUI ビルド値は Environmentstgにあり(下の「GUI のビルド値」)、翻訳・音声合成の CORS プロキシはビルド値SCRATCH_API_PROXY_ENDPOINTから組み立てる。 - 値が stg と prod で同じもの: Google / Microsoft の OAuth クライアント ID と、admin 用の Google クライアント ID。どれも stg 専用のクライアントは無く、本番と同じクライアントを使っている。これは意図した共用で、分けない(下の「OAuth クライアントを共用にする理由」)。プレビューのオリジンは本番のクライアントに登録する。
- stg の設定値のせいで、プレビューでの確認が本番どおりにならないもの: クラスの寿命(stg は 1 日)、メッシュの最大接続時間(stg は 5 分)など。テスト用に短くしてある値なので、プレビューで長く触る確認には向かない(「stg で本番どおりに動かないもの」を参照)。
| プロジェクト | stg だけにあるキー | prod だけにあるキー | 意図 |
|---|---|---|---|
| smalruby-admin | DEV_BYPASS_TOKEN |
— | 意図どおり(prod に置くと stack が throw) |
| smalruby-api | — | IMPORT_EXISTING_CUSTOM_DOMAIN / IMPORTED_REGIONAL_DOMAIN_NAME / IMPORTED_REGIONAL_HOSTED_ZONE_ID |
意図どおり(prod の api.smalruby.app は CDK の外で作ったものを import している) |
| smalruby-bug-report | DEV_BYPASS_TOKEN / BUG_REPORT_API_ENDPOINT |
— | 意図どおり(後者は integration テスト用) |
| smalruby-classroom | DEV_BYPASS_TOKEN / CLASSROOM_API_ENDPOINT |
— | 意図どおり(後者は integration テスト用) |
| smalruby-mesh-v2 | — | — | キーは同じ。手順と docs は .env.prod(手元に旧名 .env.production が残っていても、読むのは .env の symlink だけなので動く) |
| smalruby-rubytee-relay | — | — | キーは同じ |
.env.example にあって stg / prod のどちらにも無いキー(=コードの既定値で動いているもの):
- smalruby-admin:
CORS_ALLOWED_ORIGINS/ROUTE53_PARENT_ZONE_NAME/ADMIN_CUSTOM_DOMAIN - smalruby-classroom:
REPORT_DAILY_LIMIT/SHARE_DAILY_LIMIT
| プロジェクト | キー | stg | prod |
|---|---|---|---|
| 全部 | STAGE |
stg |
prod |
| smalruby-api / bug-report / classroom / rubytee-relay | CORS_ALLOWED_ORIGINS |
https://smalruby.app, https://smalruby.jp, http://localhost:8601(bug-report は :8602 も)。これに加えて、非 prod ではコードが https://preview.smalruby.app を足す |
https://smalruby.app, https://smalruby.jp |
| smalruby-admin | CORS_ALLOWED_ORIGINS(未設定 → コードの既定) |
https://smalruby.app + localhost |
https://smalruby.app |
| smalruby-bug-report | RESOLVED_TTL_DAYS |
1 | 30 |
| smalruby-classroom | CLASSROOM_TTL_DAYS |
1 | 90 |
| smalruby-classroom | MAX_STUDENT_COUNT |
50 | 100 |
| smalruby-classroom | SESSION_ACTIVE_TTL_SECONDS |
300 | 3600 |
| smalruby-classroom | PRESIGNED_URL_UPLOAD_EXPIRY / DOWNLOAD_EXPIRY |
300 / 600 | 900 / 300 |
| smalruby-classroom | JOIN_RATE_LIMIT_WINDOW_SECONDS / MAX_ATTEMPTS |
30 / 100 | 60 / 50 |
| smalruby-classroom | ARCHIVE_RETENTION_DAYS |
30 | 365 |
| smalruby-mesh-v2 | APPSYNC_CUSTOM_DOMAIN |
stg.graphql.api.smalruby.app |
graphql.api.smalruby.app |
| smalruby-mesh-v2 | ホストの heartbeat 間隔 / TTL(秒) | 15 / 60 | 60 / 150 |
| smalruby-mesh-v2 | メンバーの heartbeat 間隔 / TTL(秒) | 15 / 60 | 120 / 600 |
| smalruby-mesh-v2 | MESH_MAX_CONNECTION_TIME_SECONDS |
300 | 2100 |
| smalruby-mesh-v2 | MESH_EVENT_TTL_SECONDS / MESH_POLLING_INTERVAL_SECONDS |
5 / 1 | 10 / 2 |
| smalruby-rubytee-relay | レート制限・入力長 | 35 分 40 回・10〜250 文字 | 同じ |
秘密の値の同一性:
| 値 | stg と prod |
|---|---|
GOOGLE_CLIENT_ID / MICROSOFT_CLIENT_ID(classroom・bug-report) |
同じ(stg 専用のクライアントは無い) |
ADMIN_GOOGLE_CLIENT_ID(admin・bug-report) |
同じ |
MESH_SECRET_KEY(mesh-v2)/ MESH_ZONE_SECRET_KEY(api) |
別(stg は stg 専用の値) |
ANTHROPIC_FEDERATION_RULE_ID / ANTHROPIC_ORGANIZATION_ID / ANTHROPIC_SERVICE_ACCOUNT_ID / ANTHROPIC_WORKSPACE_ID(classroom・rubytee-relay の worker) |
Claude を Workload Identity Federation で呼ぶ値(静的な API キーは使わない)。rule と service account は Lambda ごとに別(4 つ)。workspace は stage ごとに 1 つ(機能では分けない)。rule の subject_prefix は各 Lambda の実行ロールの ARN なので stage ごとに別。設定の手順は claude-api-wif.md |
全プロジェクト共通(.claude/rules/infra/development.md の規約どおり):
- リソース名・スタック名: prod は接尾辞なし、それ以外は
-<stage> - カスタムドメイン: prod は
<service>.api.smalruby.app、それ以外は<stage>.<service>.api.smalruby.app(smalruby-api はstg.api.smalruby.app) - Lambda の source map: prod では出さない
- CloudWatch Logs の保持期間: prod 1 か月 / それ以外 1 週間(admin の prod だけ 1 年。監査記録のため)
プロジェクトごとの分岐:
| プロジェクト | 分岐 | 理由 |
|---|---|---|
| classroom / bug-report / admin | DEV_BYPASS_TOKEN は stage が prod でないときだけ受け付ける。prod の .env にあると stack が throw |
自動テスト用のログイン省略を本番で使えないようにする |
| classroom / bug-report / admin | prod の CORS に localhost が入っていると stack が throw(lib/cors-origins.ts) |
開発中に緩めた CORS の戻し忘れを防ぐ |
| classroom | SharedAssignments は prod だけ RETAIN + PITR |
消えると取り戻せないデータなので |
| classroom / bug-report | S3 の autoDeleteObjects は prod でないときだけ |
stg はスタックごと消せるようにする |
| classroom / api | HTTP API のスロットリング: prod 200/200、stg 50/50 | — |
| classroom | ルート単位のスロットリング: prod 10/20、stg 5/10 | — |
| rubytee-relay | スロットリング: prod 10/30、stg 5/10。GET /jobs は prod 40/80、stg 10/20 |
— |
| rubytee-relay | takeover worker の同時実行の上限: prod 50、stg 10 | 費用の上限 |
| rubytee-relay | 応答ログの sourceIp は prod では残さない |
個人に結び付く情報を本番で残さない |
| admin | JWT authorizer は prod だけ。prod は ADMIN_GOOGLE_CLIENT_ID が無いと throw |
stg は dev バイパス(JWT ではない)で E2E を回すため |
| mesh-v2 | X-Ray は prod でないときだけ | 費用 |
| mesh-v2 | MESH_MAX_CONNECTION_TIME_SECONDS の既定値: prod 1500、stg 300(どちらも .env で上書きしている) |
— |
| もの | stage | 備考 |
|---|---|---|
Route 53 のゾーン api.smalruby.app と、お名前.com からの NS 委任 |
共通 | 各スタックは fromLookup で参照するだけ |
api.smalruby.app の API Gateway カスタムドメイン・ACM 証明書・A レコード |
prod だけ | 旧 SAM 時代に作ったものを import している。stg の stg.api.smalruby.app は CDK が作る |
| GitHub Actions の OIDC デプロイ用 IAM ロール | stg 用(repo Variables の AWS_DEPLOY_ROLE_ARN)と prod 用(Environment prod の Variables) |
docs/infra-deploy/README.md |
管理者の登録(bug-report の BugReportAdmins、admin の SmalrubyAdmins) |
両方 | 手で登録する。stg には自動テスト用の dev-admin@example.com がある |
| Google / Microsoft の OAuth クライアント | 共通(1 つずつ) | stg 専用は作らない(意図した共用) |
smalruby.app の配信(外部リポジトリ smalruby/smalruby.app + デプロイキー) |
prod だけ | GUI の本番配信 |
プレビューを stg に向けたあと、プレビューで確かめにくくなるもの。どれもテスト用に短くした設定値によるもので、プレビューの用途(変更の確認)では困らない。
- クラスの寿命が 1 日(
CLASSROOM_TTL_DAYS=1)。前日にプレビューで作ったクラスは翌日には消える。 - メッシュの最大接続時間が 5 分(
MESH_MAX_CONNECTION_TIME_SECONDS=300)。授業の長さの通しの確認はできない。 - 授業中を想定した負荷(生徒数の上限 50・スロットリングが低い)は再現しない。
- admin の JWT authorizer は stg に無い(意図した違い)。
- データは消えうる。stg のテーブルは
SharedAssignmentsも含めて DESTROY で、PITR も無い。
GUI のビルド(webpack の DefinePlugin)が使う環境変数と、それぞれの stg の値がどこにあるか。プレビュー用のビルドは、Environment stg の値で repo の値(prod)を上書きして stg を向く。
| 変数 | 今の GitHub での置き場所(prod の値) | stg の値 | 置き場所 |
|---|---|---|---|
MESH_GRAPHQL_ENDPOINT |
repo Secret | stg.graphql.api.smalruby.app |
Environment stg の Secret |
MESH_API_KEY |
repo Secret | stg の AppSync の API キー | Environment stg の Secret |
MESH_AWS_REGION |
repo Secret | 同じ(ap-northeast-1) |
— |
RUBYTEE_RELAY_ENDPOINT |
repo Secret | stg.rubytee.api.smalruby.app |
Environment stg の Secret |
CLASSROOM_API_ENDPOINT |
repo Secret | stg.classroom.api.smalruby.app |
Environment stg の Secret |
BUG_REPORT_API_ENDPOINT |
repo Secret | stg.bug-report.api.smalruby.app |
Environment stg の Secret |
SCRATCH_API_PROXY_ENDPOINT |
repo Variable | https://stg.api.smalruby.app |
Environment stg の Variable(翻訳・音声合成の CORS プロキシにも使う) |
GOOGLE_CLIENT_ID / MICROSOFT_CLIENT_ID |
repo Secret | prod と同じ値 | そのまま使える |
GOOGLE_API_KEY |
repo Secret | stg 専用は無い | そのまま使える |
MAX_USER_MESSAGE_LENGTH / MIN_USER_MESSAGE_LENGTH |
repo Variable | prod と同じ値(250 / 10) | そのまま使える |
MESH_*_INTERVAL_MS |
repo Variable | stage の区別なし(クライアントの調整値) | そのまま使える |
GTM_ID / GTM_ENV_AUTH |
repo Secret(GTM_ENV_AUTH は未登録) |
プレビューでは使わない | — |
ADMIN_API_ENDPOINT / ADMIN_GOOGLE_CLIENT_ID |
repo Variable | 管理 SPA 用。エディタのプレビューでは使わない | — |
補足:
DEV_BYPASS_TOKENは GUI のビルドには埋め込まない。プレビューでは URL の?devlogin=<DEV_BYPASS_TOKEN>で渡す。- 翻訳(
scratch3_translate)と音声合成(scratch3_text2speech)の CORS プロキシの URL は、ビルド値SCRATCH_API_PROXY_ENDPOINTから<endpoint>/cors-proxyとして組み立てる(既定https://api.smalruby.app)。
いまは無い。
Google / Microsoft の OAuth クライアントと、admin 用の Google クライアントは、stg と prod で同じものを使い、分けない。 「stg と prod は設定値以外まったく同じ」の例外として、ここに理由を残す。
- 分けると手間が倍になる: stg 専用のクライアントを作ると、同意画面・承認済みのオリジン・リダイレクト URI・ ドメインの確認を 2 組そろえ続けることになる。片方だけ直し忘れると、stg と prod でログインの挙動がずれる。
- 共用の危険は小さい: 増えるのは、本番のクライアントに登録するプレビューのオリジン
(
https://preview.smalruby.appと、Microsoft のリダイレクト URIhttps://preview.smalruby.app/auth-redirect.html)だけ。 どちらも自分たちのドメインで、ほかの人がそこにページを置くことはできない。 - ログインしたあとのデータは stg と prod で分かれている: クライアントが同じでも、ID トークンを受け取って検証するのは それぞれの stage の API で、データ(クラス・課題など)は stage ごとのテーブルにある。プレビューでログインしても、 本番のデータには触れない。
分けるのは、たとえば「stg だけ同意画面のスコープを変えて試したい」ような、stage ごとにクライアントの設定を変える 必要が出たときにする。