はじめに Stable

TenkaCloud にはいくつかの実行モードがあります。今日やりたいことに合う行を 選んでください。ローカル、Codespaces、Liteは実行手順です。SaaSはコード構成を 説明する参考情報であり、現在のセルフサービス導入手順ではありません。

プラットフォーム開発、競技開催、競技参加、問題作成のどれを行うか決まっている場合は、 役割別マニュアルから始めてください。

モード 4〜5 の概念的な背景（各スタックが何であるか、テナントがどのように プロビジョニングされるか）は デプロイモードと起動パスにまとめています。

1. ローカルドリル — Docker、AWS 不要

クラウドに依存しないドリル問題は、ローカル採点 API を備えた自己完結型の Docker コンテナとして動作します。AWS には一切触れず、費用もかかりません。

前提条件: Bun 1.3.11 と、起動中の Docker デーモン （Docker Desktop、macOS では colima も可）。make doctor は何もインストール せずにセットアップ状況を診断します。ガイド付きインストーラーを使いたい場合は make local-onboard を実行してください。CPU・メモリ・Docker への割り当て・ 空きディスクは 3 つの実行プロファイルとして実測値付きで docs/local-play-requirements.md に公開しています。make doctor PROFILE=recommended で手元のマシンと比較できます。

git clone https://github.com/susumutomita/TenkaCloud.git
cd TenkaCloud
make install
git submodule update --init problems   # the drill catalog
make local

make local はローカル採点 API を起動し、Participant Portal（ポート 5175）を 開きます。ドリルの選択と開始はポータル画面から行います。便利なバリエーション:

make local-list                # list every drill id
make local PROBLEM=<drill-id>  # pre-start one drill
make local-status              # what is running
make local-down                # stop everything

ローカルプレイの完全なマニュアル — /verify 採点コントラクトや、独自の コンテナドリルの作成方法 — は docs/local-play.md にあります。

2. GitHub Codespaces — インストール不要

同じローカルドリルを、codespace をマシンとして実行します。セットアップは 自動です（初回ビルドで Bun のインストール、ドリルカタログの初期化、Docker の 起動が行われます）。

1. このリポジトリの github.com/codespaces/new を開き、Create codespace on main を選択します。
2. 「▷ ローカルプレイ開始」 タスクを実行します（コマンドパレット → Tasks: Run Task、または Cmd/Ctrl+Shift+B）。make local が自動で 実行されます。
3. Participant Portal が起動したら、PORTS タブを開き、ポート 5175 の 横にあるプレビューアイコンをクリックします。

Codespaces セッションを快適に保つためのルールは 2 つです。

• codespace の中で完結させてください。 ドリルのリンクはポート 5175 の プレビュー URL 経由でのみ機能します。手元のマシンのブラウザタブに 127.0.0.1 の生 URL を貼り付けても解決できません。
• API 型のドリルには codespace のターミナルから回答します（例: curl http://localhost:<port>/...）。フォワードされたポートは codespace 内 だけのプライベートなものだからです。いずれの場合も、ポータルにはドリルの エンドポイントが表示されます。

Codespaces でプレイできるのはクラウド非依存のドリルのみです。AWS にデプロイ する問題にはモード 3、4、5 のいずれかが必要です。

3. AWS 上の Lite モード — コンソールランチャー、ローカルインストール不要

Lite モードは単一主催者向けのプラットフォームです。Admin Console、 Participant Portal、問題デプロイバックエンドを、固定の単一テナントを持つ 2 つの CloudFormation スタックとしてデプロイします。このパスでは AWS コンソールだけで構築が完結します。ランチャースタックが CodeBuild プロジェクトを作成し、それがリポジトリをクローンしてデプロイを実行して くれます。

1. infrastructure/templates/lite-pipeline.yaml をダウンロードします。
2. CloudFormation の Create stack ページを開き（カタログのデフォルトは ap-northeast-1 を対象としています）、Upload a template file で アップロードして、スタック名を tenkacloud-lite-launcher にします。
3. TenantAdminEmail（唯一の必須パラメータ）に、Admin Console の招待 メールを受け取るメールアドレスを設定します。
4. IAM ケーパビリティのチェックボックスを承認し、スタックを作成します。
5. スタックの StartBuildConsoleUrl 出力から CodeBuild プロジェクトを 開き、Start build を押します。

約 15〜30 分後、ビルドが作成した tenkacloud-lite スタックと tenkacloud-lite-problem-deploy スタックの Outputs に Admin Console と Participant Portal の URL が表示されます。TenantAdminEmail に届いた 一時パスワードでサインインしてください。

完全に破棄する場合: 同じ CodeBuild プロジェクトで ACTION=destroy-all を指定して Start build with overrides を実行します。 これにより Lite スタックが所有する DynamoDB テーブルと問題デプロイ用ログも 削除されます。成功後に tenkacloud-lite-launcher スタック自体を削除して ください。DynamoDB 履歴を残す場合だけ ACTION=destroy を使います。 destroy-all 追加前の launcher は、先に CloudFormation のスタック更新で 最新版のテンプレートを適用してください。旧 buildspec は未知の ACTION を deploy として扱うため、旧 launcher に destroy-all を直接指定してはいけません。

4. AWS 上の Lite モード — CLI

モード 3 と同じ 2 つのスタックを、シェルからデプロイします。プラットフォーム 自体の開発も行う場合はこちらを選んでください。

前提条件: Bun 1.3.11 と、対象アカウント向けの AWS 認証情報（プロファイル または SSO）がシェルに設定されていること。cdk bootstrap を別のステップ として実行する必要はありません — デプロイが冪等に実行します。また Lambda のバンドルにはローカルの esbuild を使うため、Docker は不要です。

git clone https://github.com/susumutomita/TenkaCloud.git
cd TenkaCloud
make install
git submodule update --init problems

# 1. 環境ファイルを作成します（対話式ウィザード）…
make env-init
# …または example をコピーして AWS_ACCOUNT_ID と TENANT_ADMIN_EMAIL を記入します:
#   cp infrastructure/environments/development/.env.example \
#      infrastructure/environments/development/.env

# 2. デプロイ（SPA のビルド、必要なら CDK bootstrap、2 スタックのデプロイ）
make deploy

コマンドが完了すると、Admin Console と Participant Portal の URL が表示 されます。環境の切り替えは make deploy ENV=production で行い（環境ごとに 専用の infrastructure/environments/<env>/.env があります）。完全削除は make destroy-all、DynamoDB 履歴を残すスタック削除は make destroy で行います。

コントロールデータのバックエンドを選ぶ: DynamoDB か Turso か

Lite モードはコントロールデータ（イベント、チーム、デプロイメント、スコア）を 2 つのバックエンドのいずれかに保存します。選択は .env の CDK_PARAM_CONTROL_DATA_BACKEND で行います。

設定値はこの 2 つだけです。2 つのストアが同期することはないため、最初の本番 イベントの前に環境ごとにバックエンドを決めてください（後からの切り替えは フラグの変更ではなくデータ移行になります）。

Turso経路は単体テストとCDK synthでは確認されていますが、実Turso、新規AWSデプロイ、 請求までを組み合わせたライブ検証は未実施です。最初の本番競技ではDynamoDBを選んでください。

Turso へのオプトインは 4 ステップです。Turso データベースを作成し、その認証 トークンを SecureString として SSM に保存し、.env に 3 行 （CDK_PARAM_CONTROL_DATA_BACKEND=turso に加えて CDK_PARAM_TURSO_DATABASE_URL と CDK_PARAM_TURSO_AUTH_TOKEN_PARAMETER_NAME）を追加して、make deploy を 実行します。SQL スキーマは Lambda の初回コールドスタート時に自動作成され、 バックエンドが設定されているのに Turso のいずれかの値が欠けている場合は デプロイゲートが即座に失敗します。 完全なウォークスルー、既存の DynamoDB バックエンドのスタックからの移行パス、 実測の月額コスト、現在のライブ検証ステータスは docs/running-costs.md にあります。

5. SaaS モード — マルチテナント

SaaS モードはフルマルチテナントプラットフォームを構築します。System Admin 招待を備えた SBT コントロールプレーン、pooled の BASIC/ADVANCED テナント、 専用の PLATINUM silo スタックが立ち上がります。複数の組織が同じ デプロイメント上でイベントを運営する場合に選択してください。そうでなければ Lite モードが適切なデフォルトです。

現在の状態: make deploy-saasと関連コードは存在しますが、最近の新規AWS環境で、 導入、テナント作成、問題起動、採点、削除までを通した確認は記録されていません。 以下は構成を読むための参考であり、本番開催向けの確認済み手順ではありません。

前提条件: モード 4 と同じツールチェーンに加え、 infrastructure/environments/<env>/.env に SYSTEM_ADMIN_EMAIL と AWS_ACCOUNT_ID が必要です。

make deploy-saas

この 1 コマンドで 3 つのフェーズがすべて実行されます。コントロールプレーンと pooled アプリケーションプレーンのデプロイ（フェーズ 1）、Admin Console の ビルドと CloudFront での配信（フェーズ 2）、そして CloudFront オリジンを Cognito のコールバック/CORS に組み込んだ上でのコントロールプレーンの再デプロイ （フェーズ 3）です。System Admin の招待メールは SYSTEM_ADMIN_EMAIL に 届きます。Admin Console からテナントを作成すれば、あとはテナント管理者が 引き継ぎます。

破棄は make destroy-saas で行います。どの部分的な状態からでも冪等に動作 します。テナントがどのようにプロビジョニングされるか（pooled と silo の違い、 CodePipeline が実際に何のためにあるのか）は デプロイモードと起動パスで解説して います。

次のステップ

• 問題を出す: 初めてのパックのチュートリアル と問題パックのコンセプト。
• 競技をエンドツーエンドで運営する: イベントを運営する。
• スタックを理解する: プラットフォームアーキテクチャ。