Update DEVELOPMENT.md (#50)

icoxfog417 · Takahiro Kubo · web-flow · commit 65431ed822e9 · 2024-02-14T11:12:55.000+09:00
* Update DEVELOPMENT.md

* Update DEVELOPMENT.md

---------

Co-authored-by: Takahiro Kubo &lt;ttaakkaa@amazon.co.jp&gt;
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
@@ -16,11 +16,169 @@ AWS が初めての場合、 AWS 、特に本プレイグラウンドで利用
 
 ## 開発環境構築
 
-[README.md](../README.md) のデプロイのセクションのセットアップを行ってください。
+開発に使用する環境を整えます。以降の手順は手元の PC での構築を前提にしていますが、 Cloud9 などリモートの環境を使用することで、お手元の PC に影響を与えずデプロイすることができます。 Cloud9 を使用したデプロイ方法については[動画](https://youtu.be/9sMA17OKP1k?si=XwEp7q6b_EXDBP3p)にまとめていますので、そちらを参考にセットアップを行ってください。
 
-### フロントエンドの開発
+1 から 4 の手順を踏むことで、開発環境を構築し修正を送る手続きが確認できます。
 
-次に、ローカルでアプリケーションを実行し開発する方法を示します。
+### 1.AWS 環境に接続する
+
+プレイグラウンドをデプロイする AWS アカウントにアクセス可能なユーザーを作成し、そのユーザーで AWS アカウントにアクセスできることを確認してください。プレイグラウンドは  [AWS Cloud Development Kit](https://aws.amazon.com/jp/cdk/)（以降 CDK）を使いデプロイするため実行の権限が必要です。
+
+#### 1.1 権限の設定
+
+プレイグラウンドのデプロイに必要な権限の設定例を示します。ユーザーグループとして設定しておくと複数ユーザーへの権限付与が容易になります。
+
+* AmazonDynamoDBReadOnlyAccess
+* AWSLambda_ReadOnlyAccess
+* CloudWatchReadOnlyAccess
+* CdkDeploy (※カスタム)
+* CreateUserAccessKey (※カスタム)
+
+CdkDeploy の設定
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Sid": "AssumeCDKRoles",
+            "Effect": "Allow",
+            "Action": "sts:AssumeRole",
+            "Resource": "*",
+            "Condition": {
+                "ForAnyValue:StringEquals": {
+                    "iam:ResourceTag/aws-cdk:bootstrap-role": [
+                        "image-publishing",
+                        "file-publishing",
+                        "deploy",
+                        "lookup"
+                    ]
+                }
+            }
+        }
+    ]
+}
+```
+
+CreateUserAccessKey の設定
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Action": [
+                "iam:ListUsers",
+                "iam:GetAccountPasswordPolicy"
+            ],
+            "Resource": "*"
+        },
+        {
+            "Effect": "Allow",
+            "Action": [
+                "iam:*AccessKey*",
+                "iam:ChangePassword",
+                "iam:GetUser"
+            ],
+            "Resource": [
+                "arn:aws:iam::*:user/${aws:username}"
+            ]
+        }
+    ]
+}
+```
+
+#### 1.2 権限の設定
+
+AWS のユーザーを作成したら、 [AWS CLI](https://docs.aws.amazon.com/ja_jp/cli/latest/userguide/cli-chap-welcome.html) を使い AWS にアクセスできるか確認してください。
+
+手順は次の記事などを参考にしてください。
+
+* [【AWS】aws cliの設定方法](https://zenn.dev/akkie1030/articles/aws-cli-setup-tutorial)
+* [AWS CLI初期設定手順（Linux）](https://blog.serverworks.co.jp/2023/08/25/150000)
+
+※ LLM 勉強会の AWS アカウントで開発する際は、開発環境のリージョンは東京 (`ap-northeast-1`) としてください。
+
+#### Checkpoint:1
+
+* デプロイしたい AWS アカウントにアクセス可能な IAM ユーザーが作成できている。
+* 作成した IAM ユーザーの認証情報を使い、 AWS アカウントにアクセスできることを確認した。
+   * 開発環境のリージョンは東京 (`ap-northeast-1`) としてください。
+
+### 2.ソースコードをダウンロードする
+
+プレイグラウンドのリポジトリからソースコードをダウンロードします。
+
+```
+git clone https://github.com/llm-jp/llm-jp-model-playground.git
+```
+
+Git のインストール方法や使い方は下記を参照してください
+
+* [使い始める Git](https://qiita.com/icoxfog417/items/617094c6f9018149f41f)
+
+GitHub を使う場合、 GitHub CLU だとクレデンシャルの設定なのが非常に容易なためこちらを使うことを推奨します。
+
+* [GitHub CLI クイックスタート](https://docs.github.com/ja/github-cli/github-cli/quickstart)
+
+#### Checkpoint:2
+
+* Git を用い、開発環境にソースコードがダウンロードできている。
+
+### 3. アプリケーションの動作確認
+
+CDK を用い自身の開発環境にデプロイを行い、動作確認をします。
+
+#### 3.1 CDK のインストール
+
+各環境での CDK のインストール方法は [AWS CDK Workshop](https://cdkworkshop.com/ja/15-prerequisites/100-awscli.html) の「必要条件」を参照ください。本リポジトリでは TypeScript を使っているため、 Python/.NET/Java/Go の環境構築は必要ありません。
+
+#### 3.2 CDK によるデプロイ
+
+CDK のインストールができたらデプロイを開始します。ターミナルを開き、 `git clone` したフォルダまで異動していることを確認したのち次の手順を実行してください。
+
+LLM 勉強会の AWS アカウントで開発する際は、開発環境のリージョンは東京 (`ap-northeast-1`) としてください。
+
+Mac/Linux
+
+```bash
+export AWS_DEFAULT_REGION=ap-northeast-1
+```
+
+Windows
+```bash
+set AWS_DEFAULT_REGION=ap-northeast-1
+```
+
+次に、本アプリケーションに必要な `npm` のパッケージをインストールします。
+
+```bash
+npm ci
+```
+
+CDK を利用したことがない場合、初回のみ CDK 用のファイルを保存する Amazon S3 やデプロイに必要なアクセス権限を付与する IAM ロールを準備する [Bootstrap](https://docs.aws.amazon.com/ja_jp/cdk/v2/guide/bootstrapping.html) 作業が必要です。すでに Bootstrap された環境では以下のコマンドは不要です。
+
+```bash
+npx -w packages/cdk cdk bootstrap
+```
+
+続いて、以下のコマンドで AWS リソースをデプロイします。デプロイが完了するまで、お待ちください（20 分程度かかる場合があります）。 LLM 勉強会のアカウントで作業する場合、 `<stage>` にはご自身のユーザー ID を設定してください。デプロイ先が重複しないようにするために必要です。
+
+```bash
+npm run cdk:deploy -- -c stage=<stage>
+```
+
+アプリケーションのデプロイが完了したら、コンソールに出力される `WebUrl` の URL からアクセスしてください。コンソールの出力をとり漏らした場合は、  AWS Console にログインし次の手順で確認してください。
+
+1. 画面上部の検索バーで "CloudFormation" を検索し、 CloudFormation の管理画面に遷移。
+   * この時、 AWS のリージョンが CDK deploy したリージョンで同じであることを確認してください。
+2. 左側のメニューから「スタック」を選択。メインパネルに表示されたスタックの一覧から "GenerativeAiUseCasesStack" を選択。
+3. 画面右にスタックの情報が出力される。「出力」のタブからキーが "WebUrl" になっているものを探すと、値の箇所に URL が記載されている。
+
+URL にアクセスするとログイン画面に遷移します。
+
+#### 3.3 フロントエンドの開発
+
+構築した開発閑居でアプリケーションを実行し開発する方法を示します。
 
 **Unix 系コマンドが使えるユーザー (Linux, MacOS 等)**
 
@@ -61,9 +219,9 @@ export VITE_APP_REGION=ap-northeast-1
 npm run web:dev
 ```
 
-正常に実行されれば http://localhost:8080 で起動しますので、ブラウザからアクセスしてみてください。
+正常に実行されれば http://localhost:8080 で起動しますので、ブラウザからアクセスしてみてください。プレイグラウンドの内部に入るためにはプレイグラウンドのアカウントが必要です。作成する手順は [README.md](../README.md) の「アカウント作成手順」を参照してください。
 
-### バックエンドの開発
+#### 3.4 バックエンドの開発
 
 次にバックエンドを開発する時の方法を示します。
 
@@ -84,7 +242,7 @@ npm run cdk:watch -- -c stage=<stage>
 裏ではファイルの変更がモニタされ Lambda への変更はホットスワップデプロイが実行され、CDK の更新なしにバックエンドにデプロイすることが可能です。その他の変更は通常の CloudFormation の完全なデプロイにフォールバックします。
 詳細ついては [CDK Workshop](https://cdkworkshop.com/ja/20-typescript/30-hello-cdk/300-cdk-watch.html#cdk-watch) をご確認ください。
 
-### モデルの動作確認
+#### 3.5 モデルの動作確認
 
 プレイグラウンドで扱えるモデルは、 Amazon SageMaker にデプロイしています。具体的には、 Deep Java Library (DJL) を使用した SageMaker Endpoint に対応しています。
 
@@ -109,6 +267,33 @@ npm run cdk:watch -- -c stage=<stage>
 4. `npm run cdk:deploy` でモデルをデプロイする。
 5. モデルを反映させるためにはエンドポイントを再起動する必要があるため、一度エンドポイントを落として立ち上げ直す。
 
+#### Checkpoint:3
+
+* CDK をインストールし、プレイグラウンドがデプロイできることを確認した。
+* フロントエンドの動作確認を行った。
+* バックエンドの動作確認を行った。
+* モデルの追加手順を確認した。
+
+### 4. 修正を本番環境に反映する
+
+修正した内容を本番環境に反映する手順は次の通りです。
+
+1. 修正を行う
+2. 動作検証のために、個人環境にデプロイをする
+   * `aws configure` で、デフォルト `region` を開発環境のリージョン (tokyo) に設定
+   * `cdk deploy` する際に、自分のAWSユーザー名を context で指定する (忘れても別 region なので本番が修正されることはない)。
+3. 動作検証を実施
+4. `main` ブランチに PR を作成する
+5. レビュアーは、自分の環境に PR のコードをデプロイして動作確認をする。
+6. PR がマージされる
+7. マージされると本番環境に自動デプロイされる
+
+#### Checkpoint:4
+
+* 修正を行う手順を確認した。
+* Pull Request を作成できた。
+* マージ後、本番環境に修正が反映されることを確認した。
+
 ## その他設定
 
 ### セルフサインアップを有効化する
