sesame-onboard

Sesame セルフホストのセットアップガイド

ユーザーが sesame deploy aws を実行できるよう案内します。このコマンドは、ユーザー自身の AWS アカウントに EC2 と RDS をプロビジョニングし、HTTPS ダッシュボードの URL を返します。あなたの役割は、前提条件を満たしていることを確認し、各入力値について説明して、ドライランですべての値を収集・確認したうえで、デプロイすることです。

セルフホストの完全なデプロイガイドや CLI リファレンスなどの追加ドキュメントは、https://docs.getsesame.dev でご覧いただけます。

デプロイの実行方法

• sesame deploy aws は、Google サインインの場合を除き、フラグを使って非対話的に実行します。Google サインインの場合は、クライアントシークレットがチャットに表示されないよう、ユーザー自身が実行します（下記とステップ 7 を参照）。エージェントがコマンドを実行するときは TTY がないため、CLI の対話型プロンプトは表示されません。すべての操作はフラグで行います。つまり、あなたの役割は、各値を収集し、Google クライアントシークレット以外のすべての値をフラグとして渡すことです。
• AWS キー： 絶対に取り扱わないでください。ユーザー自身で AWS CLI にログインしてもらい、あなたは aws sts get-caller-identity で確認するだけです。
• Google クライアントシークレット： あなたが絶対に知ってはならない唯一の値です。チャットで受け取らず、--google-client-secret も絶対に渡さないでください。 入手方法を案内し（ステップ 4）、手元に用意できていることを確認します。 ただし、Google サインインを有効にする場合は、ユーザー自身にデプロイを実行してもらいます（ステップ 7）。CLI は非表示の TTY 入力でシークレットを求めるため、シークレットがあなたやコマンド履歴を経由することはありません。クライアント ID は公開識別子なので、あなたが --google-client-id を渡しても問題ありません。シークレットが手元にあることをユーザーが確認するまで、先に進まないでください。作成には数分かかり、一度しかコピーできません。
• 管理者セットアップリンク（/setup?token=…）： デプロイ時に、機密トークンを含む一度限りの管理者セットアップリンクが出力されます。これはシークレットとまったく同じように扱ってください。ユーザーに貼り付けを求めたり、内容を引用、繰り返し、要約したり、保存したりしないでください。 管理者パスワードの設定は、ユーザー自身にリンクを開いて行ってもらいます。デプロイ後に必要なのはダッシュボード URLと（Google を使う場合は）リダイレクト URIだけで、どちらもシークレットではありません。
• 一度に 1 つのステップずつ進め、次に移る前に各値を確認してください。

---

ステップ 0 — Sesame CLI はインストールされていますか？

デプロイ全体を sesame CLI で実行するため、何よりも先にインストールされていることを確認してください。

sesame --version

「command not found」と表示された場合は、インストールしてからもう一度実行してください。正常に動作するまで先に進まないでください。

curl -fsSL https://getsesame.dev/install.sh | sh

ステップ 1 — AWS CLI はインストールされていますか？

aws --version

「command not found」と表示された場合は、インストールしてください。

• macOS： brew install awscli（Homebrew がない場合：curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o /tmp/AWSCLIV2.pkg && sudo installer -pkg /tmp/AWSCLIV2.pkg -target /）
• Linux： curl "https://awscli.amazonaws.com/awscli-exe-linux-$(uname -m).zip" -o /tmp/awscliv2.zip && unzip -q /tmp/awscliv2.zip -d /tmp && sudo /tmp/aws/install

aws --version を再実行して確認してください。

ステップ 2 — AWS にログインしていますか？

aws sts get-caller-identity

• アカウント ID と ARN が出力された場合： ログイン済みです。アカウント ID と ARN をユーザーに示し、デプロイ先として希望するアカウントであることを確認してください。
• エラーが発生した場合： ログインが必要です。ユーザー自身で次のいずれか1 つを実行するよう伝えてください（あなたがキーを扱ってはいけません）。
  • アクセスキー：aws configure（アクセスキー ID、シークレット、リージョンの入力を求められます）。
  • SSO：aws configure sso を実行してから、aws sso login を実行します。 続けて aws sts get-caller-identity を再実行し、確認してください。

この ID に必要な IAM 権限として、次の管理ポリシーをアタッチしてください：AWSCloudFormationFullAccess、AmazonEC2FullAccess、AmazonRDSFullAccess、IAMFullAccess、SecretsManagerReadWrite、AmazonSSMFullAccess（最後のポリシーがあると、後から sesame deploy update/restart/logs でボックスにアクセスできます）。ポリシーが不足していると、そのサービスで AccessDenied が発生してデプロイに失敗するため、ユーザーに伝えてください。ステップ 5 のドライランでも、まったく同じ一覧が出力されるため、デプロイ前に必要な権限があるか確認できます。

ステップ 3 — ティア 1（必須）— ユーザーから情報を収集する

以下を尋ね、確認します。

• 管理者メールアドレス — 最初のダッシュボード管理者のメールアドレスです（例：[email protected]）。
• AWS リージョン — デフォルトは us-east-1 です。別のリージョンを希望するか尋ねます。
• データベース — デフォルトは rds（マネージド Postgres）です。bundled は EC2 上で Postgres を実行します（より低コストで、別の DB は不要です）。ほとんどの場合、デフォルトで問題ありません。

これらは秘密情報ではないため、チャットで収集しても問題ありません。

ステップ 4 — ティア 2（任意）：Google Workspace サインイン

次のように尋ねます。「ダッシュボードで『Google でログイン』を使いますか？それともメールアドレス＋パスワードだけにしますか？」 パスワードのみの場合は、ステップ 5 に進みます。

使う場合は、一度に 1 つずつクリックするよう案内します。

1. Google Cloud プロジェクトを作成／選択する： https://console.cloud.google.com/projectcreate （または既存のものを選択します）。
2. 同意画面を設定する： https://console.cloud.google.com/auth/overview →「Get started」。
   • アプリ名とサポート用メールアドレスを設定します。
   • 対象ユーザー：
     • Google Workspace を利用している場合 → Internal を選択します（サインインを Workspace 組織内に制限します）。
     • Workspace を利用していない場合 → External を選択し、Audience → Test users → Add users を開いて、ログインに使うメールアドレスを追加します。
3. OAuth クライアントを作成する： https://console.cloud.google.com/auth/clients → Create client → アプリケーションの種類で Web application を選択 → 名前を「Sesame」にします。
4. リダイレクト URI — 今は設定しないでください。 デプロイの URL によって決まります（この時点ではまだ存在しません）。デプロイ後（ステップ 7）に追加します。最終的なリダイレクト URI を設定せずにクライアントを保存して問題ありません。
5. Client ID と Client Secret をコピーします。（シークレットがすでに作成されていて再表示できない場合は、+ Add secret をクリックして新しいものを作成します。）
   • ⚠ シークレットは手元に保管し、CLI のプロンプトに入力するよう伝えてください。こちらに貼り付けないでください。
6. 許可するドメイン：
   • Workspace の場合： ドメインを指定します（例：company.com）。その Workspace のアカウントのみサインインできます。
   • Workspace を利用していない場合／個人の Gmail の場合： 空欄のままにします。個人の Gmail には Workspace の hd クレームがないため、ドメインを設定すると締め出されてしまいます。空欄にすると、確認済みの Google アカウントがすべて許可されます。ステップ 3 の管理者メールアドレスでログインするよう伝えてください。

準備状況の確認 — 次に進む前に行います。 ユーザーに、はっきりと次のように尋ねます。「Client ID と Client Secret の準備はできていますか？」 まだ準備できていなくても問題ありません。準備ができるまで上記の手順を案内します。手元にそろっていることを記録します（ID とシークレット）。両方そろったことを確認するまで、デプロイを開始しないでください。シークレットをこちらに貼り付けてもらう必要はありません。手元にあることを確認するだけで十分です。

ステップ 5 — ドライランで確認する（デプロイなし）

収集した情報からフラグのリストを作成し、--dry-run を付けて実行します。

sesame deploy aws --dry-run \
  --admin-email <email> --region <region> --database <rds|bundled> \
  [--google-oauth --google-client-id <id> \
   --google-allowed-domain <domain-or-omit-if-none>]

すべての値が確定した Plan が出力され、何もデプロイされません。ドライランでは Client Secret は不要です。Plan をユーザーに読み上げ、実際に実行する前に値を修正します。（Workspace を利用していない場合は、--google-allowed-domain を省略します。）

ステップ 6 — 必要事項のまとめ

実際にデプロイする前に、必要事項をユーザーにまとめて伝えます。

• ✅ AWS CLI にログイン済み → アカウント <id>
• 管理者メールアドレス：<email>
• リージョン：<region> · データベース：<rds|bundled>
• Google サインイン：オン／オフ
  • （オンの場合）Client ID：提供済み · Client Secret：手元にあり（デプロイ実行時に非表示のプロンプトに入力） · 許可するドメイン：<domain or "(none)">
  • （オンの場合）デプロイ後に追加するリダイレクト URI：https://<broker-url>/v1/auth/google/callback

ステップ 7 — デプロイ

パスワードのみ（Google サインインなし）： 入力シークレットは関係しないため、実行してください。同じフラグを使い、--dry-run を付けずに実行します：

sesame deploy aws \
  --admin-email <email> --region <region> --database <rds|bundled>

デプロイの出力には、一度限りの管理者セットアップリンク（/setup?token=…）が含まれます。 コマンドを実行したため、そのリンクはユーザーが確認できるコマンド出力にすでに表示されています。 **リンクやそのトークンを繰り返し表示、再掲、要約しないでください。ステップ 8 では、デプロイ出力にあるリンクを開くようユーザーに案内するだけにしてください。**ダッシュボード URL だけをユーザーに伝えてください。

**Google サインインを使う場合：**クライアントシークレットをあなたが受け取ってはいけないため、ユーザー自身のターミナルでデプロイを実行してもらいます。このコマンドは自分で実行しないでください（TTY がないため、非表示のシークレット入力プロンプトを表示できず、CLI は --google-client-secret を指定するよう求めるエラーで終了します）。クライアント ID は公開情報なので含めても問題ありません。次のコマンドを実行するようユーザーに伝えてください：

# The USER runs this in their own terminal — NOT the agent.
sesame deploy aws \
  --admin-email <email> --region <region> --database <rds|bundled> \
  --google-oauth --google-client-id <id> \
  [--google-allowed-domain <domain>]

CLI は Google client secret: と表示するので、ユーザーはそこに入力します（入力内容は非表示です）。チャットには決して入力しないでください。

--google-client-secret フラグは、対話形式ではないデプロイをスクリプトから実行するユーザー（たとえば、CI で自身のシークレットストアからシークレットを取得する場合）向けに引き続き用意されています。自身のターミナルでどう使うかはユーザー自身の判断に任されています。あなた（エージェント）は決して使用しないでください。出力するコマンドにシークレットを含めることこそ、避けようとしている行為です。

どちらの場合も、スタックのプロビジョニングには約 12〜18 分かかります（最も時間がかかるのは RDS です）。その後、次の内容が表示されます：

• ダッシュボード URL（例：https://54-159-97-177.sslip.io）
• 管理者セットアップリンク（/setup?token=…） — ⚠ 一度限りの管理者認証情報です。シークレットとして扱ってください（ユーザー自身がリンクを開きます。貼り付けたり、繰り返し表示したりしないでください）
• （Google を使う場合）正確なリダイレクト URI。

デプロイをユーザーが実行した場合（Google を使う場合）、出力はあなたではなく、ユーザーのターミナルに表示されます。ステップ 8 に必要なシークレットではない 2 つの値、ダッシュボード URL と（Google を使う場合は）リダイレクト URI だけをユーザーに尋ねてください。**管理者セットアップリンク／/setup?token=… はあなたに貼り付けないよう、必ず明確に伝えてください。これはユーザー自身が開く一度限りの管理者トークンです。**それでも貼り付けられた場合は、繰り返し表示したり、それを使って操作したりせず、破棄して、必要な 2 つの値だけをもう一度尋ねてください。

ステップ 8 — 完了

• ユーザーが（自身のデプロイ出力にある、あなたが再共有したり繰り返し表示したりしていない）セットアップリンクを開き、管理者パスワードを設定して、サインインします。
• **Google を使う場合：**OAuth クライアントに戻り（ステップ 4.4）、URI を追加 に、表示されたリダイレクト URI を指定して、保存します（数分後に反映されます）。その後、「Google で続行」をテストします（管理者のメールアドレスでログインします）。
• ダッシュボード URL がブローカーであることをユーザーに伝えてください。エージェントは sesame login --broker-url <that URL> で接続します。

失敗した場合

• CLI は失敗の理由を表示します（アプリのタイムアウト時は EC2 コンソールの出力も表示されます）。内容を伝えてください。推測はしないでください。
• 失敗してもスタックは自動削除されません。入力を修正して、sesame deploy aws を再実行してください。
• 削除するには、sesame deploy destroy --region <region> を実行します。