Skip to content

deploy-cloudshell.md

Latest commit

 

History

History
294 lines (203 loc) · 15.9 KB

deploy-cloudshell.md

File metadata and controls

294 lines (203 loc) · 15.9 KB

EN | JA

spec-driven-presentation-maker デプロイ手順

spec-driven-presentation-maker について

spec-driven-presentation-maker は、AI エージェントにプレゼンテーション生成能力を追加するオープンソースツールキットです。MCP（Model Context Protocol）ツールとして既存の AI システムに接続するだけで、対話によるスライド生成が可能になります。ローカル CLI からフルスタック Web アプリまで、ニーズに合ったレイヤーを選んで段階的に採用できます。

ワンクリックデプロイ（推奨）

ワンクリックで SDPM を AWS アカウントにデプロイできます。ローカル環境や CLI のセットアップは一切不要です。AWS コンソールにログインし、ボタンをクリックして、パラメータを入力するだけで完了します。

前提条件

ステップ 1: Launch Stack ボタンをクリック

最寄りのリージョンを選択してください：

リージョン デプロイ
東京 (ap-northeast-1) Launch Stack
バージニア北部 (us-east-1) Launch Stack
オレゴン (us-west-2) Launch Stack

ステップ 2: パラメータを入力

CloudFormation コンソールにパラメータ入力画面が表示されます。以下を設定してください：

パラメータ 説明 デフォルト
NotificationEmailAddress デプロイの開始・完了を通知するメールアドレス （必須）
DeploymentLayer layer3 = MCP Server のみ、layer4 = フルスタック（Agent + Web UI） layer4
ModelId Agent が使用する Bedrock モデル ID（例: global.anthropic.claude-sonnet-4-6） global.anthropic.claude-sonnet-4-6
EnableInvocationLogging Bedrock Model Invocation Logging の有効/無効（true / false） false
AllowedIpV4AddressRanges WAF IP 制限用の IPv4 CIDR 範囲（カンマ区切り、空欄で制限なし） （空欄）
AllowedIpV6AddressRanges WAF IP 制限用の IPv6 CIDR 範囲（カンマ区切り、空欄で制限なし） （空欄）

💡 ヒント: AllowedIpV4AddressRanges を指定してアクセスを制限することを推奨します。現在のパブリック IP は https://checkip.amazonaws.com/ で確認できます。IP 制限を設定しない場合でも、ログインには Cognito 認証が必要です。

ステップ 3: デプロイ実行

  1. 「AWS CloudFormation によって IAM リソースがカスタム名で作成される場合があることを承認します。」 にチェック
  2. スタックの作成 をクリック
  3. スタックの完了を待ちます（約 30〜40 分）。完了するとメールで通知されます。

ステップ 4: ログイン

デプロイ完了後、指定した NotificationEmailAddress 宛に仮パスワードが送信されます。通知メールに記載の Web UI URL（または CloudFormation Outputs の SdpmWebUi → SiteUrl）を開き、メールアドレスと仮パスワードでログインし、初回ログイン時にパスワードを変更すれば完了です。すぐにスライド生成を体験できます。

CloudShell を使ったデプロイ

ワンクリックデプロイのパラメータ以上にカスタマイズしたい場合（外部 IdP 連携、config.yaml による設定、deploy.sh の各種フラグ活用など）は、こちらの方法を使います。

CodeBuild がビルドとデプロイを実行するため、ローカル環境に CDK や Docker をインストールする必要はありません。以下のいずれの環境でも同じ手順でデプロイできます。

  • AWS CloudShell（ブラウザだけで完結）
  • ローカル Linux / macOS / WSL（bash と aws CLI があれば OK）

Windows はネイティブ Bash が使えないため、CloudShell または WSL をお使いください。

📌 補足: デプロイ設定は infra/config.yaml に保持できるため、再デプロイ時の一貫性を保ちやすくなります。ローカル CDK による直接デプロイ（npx cdk deploy）は開発・デバッグ用途に位置付けています。

前提条件

  • AWS マネジメントコンソールにログイン済み
  • デプロイ先アカウントで AdministratorAccess 相当の権限があること（初回デプロイ時）
  • 以下いずれかの作業環境
    • AWS CloudShell（デプロイ先リージョンで開く）
    • ローカル Linux / macOS / WSL（bash、git、aws CLI、適切な AWS 認証情報）

クイックスタート

CloudShell の場合は AWS コンソールから CloudShell を開き、ローカルの場合は任意のシェルで以下のコマンドを実行します。Layer 4（Agent + Web UI、デフォルト） が us-east-1 にデプロイされます。

cd ~
git clone https://github.com/aws-samples/sample-spec-driven-presentation-maker.git
cd sample-spec-driven-presentation-maker
chmod +x scripts/deploy.sh
./scripts/deploy.sh --region us-east-1

💡 ヒント: CloudShell のホームディレクトリ（1 GB）はセッション間で永続化されます。2 回目以降は cd ~/sample-spec-driven-presentation-maker && git pull && ./scripts/deploy.sh --region us-east-1 で最新化＋再デプロイできます。

📝 補足: ワンクリックデプロイとは異なり、この方法では Cognito ユーザーが自動作成されません。デプロイ後に Cognito ユーザーを手動で作成 して Web UI にログインしてください。

別の構成でデプロイする

上記のデフォルト（Layer 4, us-east-1）以外でデプロイしたい場合は、クイックスタートの ./scripts/deploy.sh ... 行を以下のいずれかに置き換えます。

Layer 3（MCP Server のみ）:

./scripts/deploy.sh --region us-east-1 --layer3

Bedrock Model Invocation Logging を有効化する場合:

./scripts/deploy.sh --region us-east-1 --enable-invocation-logging

注意: --enable-invocation-logging は Bedrock の Model Invocation Logging（MIL）をアカウント・リージョン単位で設定します。既に MIL が設定されている場合、スクリプトが警告を表示し、既存設定を保護するため MIL の設定を自動的にスキップします。

外部 IdP を使う場合:

./scripts/deploy.sh --region us-east-1 \
  --oidc-url "https://your-idp.example.com/.well-known/openid-configuration" \
  --allowed-clients "client-id-1,client-id-2"

WAF IP アドレス制限を有効にする場合:

# IPv4 のみ（⚠️ IPv6 アクセスはすべてブロックされます — 下記の注意を参照）
./scripts/deploy.sh --region us-east-1 --waf-ipv4 "203.0.113.0/24,198.51.100.0/24"

# IPv4 + IPv6（デュアルスタック環境では推奨）
./scripts/deploy.sh --region us-east-1 \
  --waf-ipv4 "203.0.113.0/24" \
  --waf-ipv6 "2001:db8::/32"

⚠️ IPv6 に関する注意: --waf-ipv4 のみ指定し --waf-ipv6 を省略した場合、IPv6 によるアクセスはすべてブロックされます。最近のブラウザは IPv6 を優先するため、Web UI が停止しているように見えることがあります。デュアルスタック環境では必ず両方を指定してください。

infra/config.yaml を使う場合:

infra/config.yaml が存在する場合、deploy.sh はその内容をデフォルト値として読み込みます。CLI 引数は config ファイルの値を上書きします。デプロイのたびに CLI フラグを繰り返す必要がなくなります。

cp infra/config.example.yaml infra/config.yaml
# config.yaml を編集して stacks, features, WAF 等を設定
./scripts/deploy.sh --region us-east-1

スタックの削除:

./scripts/deploy.sh --region us-east-1 --destroy

デプロイの進捗を確認する

スクリプトは CodeBuild のログをリアルタイムで表示します。 CloudShell のセッションがタイムアウトしても、CodeBuild のビルドは AWS 側で継続します。

セッションが切れた場合は、以下で結果を確認できます。

  • CodeBuild コンソール: プロジェクト名 sdpm-deploy のビルド履歴
  • CloudFormation コンソール: 各スタックのステータスと Outputs

デプロイ完了後の確認

ビルドが SUCCEEDED になると、CodeBuild のログ末尾に CloudFormation の Outputs が表示されます。 見逃した場合は CloudFormation コンソールから確認できます。

エンドポイント URL の確認

  1. CloudFormation コンソール を開く
  2. デプロイしたリージョンを選択

Layer 3（MCP Server のみ）の場合:

スタック Output キー 内容
SdpmRuntime RuntimeArn MCP Server の Runtime ARN
SdpmRuntime EndpointId Runtime Endpoint ID

Layer 4（フルスタック）の場合:

スタック Output キー 内容
SdpmAuth UserPoolId Cognito User Pool ID
SdpmAuth UserPoolClientId Cognito App Client ID
SdpmRuntime RuntimeArn MCP Server の Runtime ARN
SdpmAgent AgentRuntimeArn Agent の Runtime ARN
SdpmWebUi SiteUrl Web UI の CloudFront URL
SdpmWebUi ApiUrl REST API の URL

Cognito ユーザーの作成（Layer 4）

デフォルトの Cognito User Pool にはユーザーが存在しないため、手動で作成します。

  1. Cognito コンソール を開く
  2. User Pool 一覧から sdpm-users を選択
  3. Users タブ → Create user をクリック
  4. 以下を入力:
    • Email address: ログインに使うメールアドレス
    • Temporary password: 初回ログイン用の仮パスワード（8文字以上、大文字・数字を含む）
    • Mark email address as verified にチェック
  5. Create user をクリック

Web UI にログインする

  1. CloudFormation の SdpmWebUi スタック → Outputs → SiteUrl の URL をブラウザで開く
  2. 作成したメールアドレスと仮パスワードでログイン
  3. 初回ログイン時にパスワード変更を求められるので、新しいパスワードを設定
  4. ログイン完了後、チャット画面が表示される

CLI からユーザーを作成する場合

CloudShell から直接作成することもできます。

REGION="us-east-1"
EMAIL="user@example.com"
TEMP_PASSWORD="<任意の仮パスワード>"  # 8文字以上、大文字・数字を含むこと

USER_POOL_ID=$(aws cloudformation describe-stacks \
  --stack-name SdpmAuth \
  --query 'Stacks[0].Outputs[?OutputKey==`UserPoolId`].OutputValue' \
  --output text --region "$REGION")

aws cognito-idp admin-create-user \
  --user-pool-id "$USER_POOL_ID" \
  --username "$EMAIL" \
  --user-attributes Name=email,Value="$EMAIL" Name=email_verified,Value=true \
  --temporary-password "$TEMP_PASSWORD" \
  --region "$REGION"

SITE_URL=$(aws cloudformation describe-stacks \
  --stack-name SdpmWebUi \
  --query 'Stacks[0].Outputs[?OutputKey==`SiteUrl`].OutputValue' \
  --output text --region "$REGION")

echo ""
echo "========================================="
echo "  ユーザー作成完了"
echo "========================================="
echo "  URL:      $SITE_URL"
echo "  Email:    $EMAIL"
echo "  Password: $TEMP_PASSWORD（初回ログイン時に変更）"
echo "========================================="
echo ""
echo "上記 URL にアクセスしてログインしてください。"

オプション一覧

オプション 説明 デフォルト
--region REGION デプロイ先リージョン us-east-1
--profile PROFILE AWS CLI プロファイル —
--layer3 Layer 3 のみ（MCP Server） —
--layer4 Layer 4 フルスタック デフォルト
--enable-invocation-logging Bedrock Model Invocation Logging を有効化 無効
--oidc-url URL 外部 IdP の OIDC Discovery URL —
--allowed-clients IDS JWT の許可クライアント ID（カンマ区切り） —
--waf-ipv4 CIDRS WAF 用 IPv4 CIDR 範囲（カンマ区切り） —
--waf-ipv6 CIDRS WAF 用 IPv6 CIDR 範囲（カンマ区切り） —
--destroy 全スタックを削除 —

トラブルシューティング

CodeBuild がタイムアウトする

デフォルトのタイムアウトは 60 分です。初回デプロイで ECR イメージのビルドに時間がかかる場合があります。再実行すれば Docker レイヤーキャッシュが効いて速くなります。

権限エラーが出る

deploy.sh は CodeBuild のサービスロールに AdministratorAccess をアタッチします。IAM ロールの作成権限がない場合は、管理者にロール sdpm-deploy-role の事前作成を依頼してください。

CloudShell のストレージが足りない

CloudShell のホームディレクトリは 1 GB です。不要なファイルを削除してください。

# クローンし直す場合
rm -rf ~/sample-spec-driven-presentation-maker

--enable-invocation-logging で「既に設定済み」と警告される

Bedrock Model Invocation Logging はアカウント・リージョンで 1 つしか設定できません。既存の設定がある場合、deploy.sh は既存のログ送信先（CloudWatch Logs グループ名）を表示し、MIL の設定を自動的にスキップします。デプロイは Invocation Logging を無効にした状態で続行されます。SDPM の Invocation Logging を使用するには、既存の MIL 設定を手動で削除してから --enable-invocation-logging を付けて再実行してください。

推定月額料金

推定コストの試算と内訳は コスト試算 を参照してください。

関連ドキュメント