Merge pull request #3 from aws-samples/dev

updated README

Author: fengxu1211

README.md

@@ -1,4 +1,4 @@
-# Intelligent BI Demo
+# Generative BI Demo Application
 
 [中文文档](README_CN.md)
 ## Introduction
@@ -12,14 +12,24 @@ A NLQ(Natural Language Query) demo using Amazon Bedrock, Amazon OpenSearch with
 ### 1. Prepare EC2 Instance
 Create an EC2 with following configuration:
 
-    - Software Image (AMI): Amazon Linux 2023
-    - Virtual server type (instance type): t3.large or higher
-    - Firewall (security group): Allow 22, 80 port
+    - OS Image (AMI): Amazon Linux 2023
+    - Instance type: t3.large or higher
+    - VPC: use default one and choose a public subnet
+    - Security group: Allow access to 22, 80 port from anywhere (Select "Allow SSH traffic from Anywhere" and "Allow HTTP traffic from the internet")
     - Storage (volumes): 1 GP3 volume(s) - 30 GiB
 
 ### 2. Config Permission
-Bind an IAM Role to your EC2 instance.
-And attach an inline policy to this IAM Role with following permissions:
+
+2.1 IAM Role's permission
+
+Create a new IAM role with name genbirag-service-role and settings below:
+   - Trusted entity type: AWS Service
+   - Service: EC2
+   - Use Case: EC2 - Allows EC2 instances to call AWS services on your behalf.
+
+Skip "Add permission" and create this role first.
+
+After the role is created, and then add permission by creating inline policy as below:
 ```json
 {
     "Version": "2012-10-17",
@@ -29,7 +39,6 @@ And attach an inline policy to this IAM Role with following permissions:
             "Effect": "Allow",
             "Action": [
                 "bedrock:*",
-                "secretsmanager:GetSecretValue",
                 "dynamodb:*"
             ],
             "Resource": "*"
@@ -38,21 +47,27 @@ And attach an inline policy to this IAM Role with following permissions:
 }
 ```
 
+Finally, Bind this IAM instance profile (IAM Role) to your EC2 instance.
+
+2.2 Amazon Bedrock's Model Permission
+
 Make sure you have enabled model access in AWS Console in us-west-2 (Oregon) region for Anthropic Claude model and Amazon Titan embedding model.
+![Bedrock](assets/bedrock_model_access.png)
 
 ### 3. Install Docker and Docker Compose
 
-On the EC2 instance, log in to the SSH command line as the ec2-user user or use the AWS EC2 Instance Connect feature in the EC2 console to log in to the command line. In the session, execute the following commands. If you are not this user, you can switch with the following command: 
+Log in to the EC2 instance using SSH command as the ec2-user user or use the AWS EC2 Instance Connect feature in the EC2 console to log in to the command line. 
 
-Note: Execute each command one line at a time.
+In the session, execute the following commands. **Note: Execute each command one line at a time.**
 
+If you are not this user, you can switch with the following command: 
 ```bash
 sudo su - ec2-user
 ```
 
 ```bash  
 # Install components
-sudo dnf install docker python3-pip git -y && pip3 install docker-compose
+sudo dnf install docker python3-pip git -y && pip3 install -U awscli && pip3 install docker-compose
 
 # Fix docker python wrapper 7.0 SSL version issue  
 pip3 install docker==6.1.3
@@ -79,35 +94,40 @@ sudo sh -c "echo 'vm.max_map_count=262144' > /etc/sysctl.conf" && sudo sysctl -p
 # Clone the code
 git clone https://github.com/aws-samples/generative-bi-using-rag.git
 
-# Build docker images locally  
-cd generative-bi-using-rag/application && cp .env.template .env && docker-compose build
+# Config the Environment Variable in .env file, modify AWS_DEFAULT_REGION to the region same as the EC2 instance.
+cd generative-bi-using-rag/application && cp .env.template .env 
+
+# Build docker images locally
+docker-compose build
 
 # Start all services
 docker-compose up -d
 
 # Wait 3 minutes for MySQL and OpenSearch to initialize
 sleep 180
 ```
- Here is the English translation:
 
 ### 5. Initialize MySQL
 
 In the terminal, continue executing the following commands:
 
 ```bash
-cd initial_data && unzip init_mysql_db.sql.zip && cd ..
+cd initial_data && wget https://github.com/fengxu1211/generative-bi-using-rag/raw/demo_data/application/initial_data/init_mysql_db.sql.zip
+
+unzip init_mysql_db.sql.zip && cd ..
+
 docker exec nlq-mysql sh -c "mysql -u root -ppassword -D llm  < /opt/data/init_mysql_db.sql" 
 ```
 
-### 6. Initialize OpenSearch
+### 6. Initialize Amazon OpenSearch docker version
 
 6.1 Initialize the index for the sample data by creating a new index:
 
 ```bash 
 docker exec nlq-webserver python opensearch_deploy.py
 ```
 
-If the script fails due to any errors, delete the index and rerun the previous command:
+If the command fails due to any errors, delete the index and rerun the previous command:
 
 ```bash
 curl -XDELETE -k -u admin:admin "https://localhost:9200/uba"

README_CN.md

@@ -1,4 +1,4 @@
-# 智能BI演示
+# 生成式BI演示应用
 
 ## 介绍
 
@@ -11,14 +11,23 @@
 ### 1. 准备EC2实例
 创建具有以下配置的EC2实例:
 
-    - 软件镜像(AMI): Amazon Linux 2023
-    - 虚拟服务器类型(实例类型): t3.large或更高配置
-    - 防火墙(安全组): 允许22, 80端口 
+    - OS镜像(AMI): Amazon Linux 2023
+    - 实例类型: t3.large或更高配置
+    - VPC: 使用默认的VPC并部署在公有子网
+    - 安全组: 允许任何位置访问22, 80端口 (勾选允许来自以下对象的SSH流量和允许来自互联网的HTTP流量）
     - 存储(卷): 1个GP3卷 - 30 GiB
 
-### 2. 配置权限  
-为您的EC2实例绑定IAM角色, 可以参考[EC2文档-使用IAM角色](https://docs.aws.amazon.com/zh_cn/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html#working-with-iam-roles)
-并为此IAM角色附加以下权限的内联策略:
+### 2. 配置权限
+
+2.1 IAM Role的权限
+
+创建一个新的IAM Role，名字为genbirag-service-role，具体设置为：
+   - 信任实体：AWS服务
+   - 服务： EC2
+   - 使用场景：EC2 - Allows EC2 instances to call AWS services on your behalf.
+跳过"添加权限", 先创建出这个Role。
+
+当Role创建好之后，再通过创建内联策略来添加以下权限：
 ```json
 {
     "Version": "2012-10-17",
@@ -28,29 +37,34 @@
             "Effect": "Allow",
             "Action": [
                 "bedrock:*",
-                "secretsmanager:GetSecretValue",
                 "dynamodb:*"
             ],
             "Resource": "*"
         }
     ]
 }
 ```
+最后为你的EC2实例绑定IAM角色, 可以参考[EC2文档-使用IAM角色](https://docs.aws.amazon.com/zh_cn/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html#working-with-iam-roles)
+
+2.2 Amazon Bedrock的模型访问权限
 
 确保您已在us-west-2(美国西部(俄勒冈州))区域的AWS控制台中为Anthropic Claude模型和Amazon Titan嵌入模型启用了模型访问。
+![Bedrock](assets/bedrock_model_access.png)
 
 ### 3. 安装Docker和Docker Compose
-在EC2中，以ec2-user用户通过SSH命令行登录或者使用AWS EC2控制台的EC2 Instance Connect功能登录命令行，在会话下执行以下命令。 如果不是此用户,您可以使用以下命令切换:
+在EC2中，以ec2-user用户通过SSH命令行登录或者使用AWS EC2控制台的EC2 Instance Connect功能登录命令行，在会话下执行以下命令。
 
-注意：所有命令请一行一行执行。
+**注意：所有命令请一行一行执行。**
+
+如果不是此用户,您可以使用以下命令切换:
 
 ```bash
 sudo su - ec2-user
 ```
 
 ```bash
 # 安装组件
-sudo dnf install docker python3-pip git -y && pip3 install docker-compose
+sudo dnf install docker python3-pip git -y && pip3 install -U awscli && pip3 install docker-compose
 
 # 修复docker的python包装器7.0 SSL版本问题
 pip3 install docker==6.1.3 
@@ -77,8 +91,11 @@ sudo sh -c "echo 'vm.max_map_count=262144' > /etc/sysctl.conf" && sudo sysctl -p
 # 克隆代码
 git clone https://github.com/aws-samples/generative-bi-using-rag.git
 
+# 在.env文件里配置环境变量，修改AWS_DEFAULT_REGION为你的EC2所在的区域
+cd generative-bi-using-rag/application && cp .env.template .env 
+
 # 在本地构建docker镜像
-cd generative-bi-using-rag/application && cp .env.template .env && docker-compose build
+docker-compose build
 
 # 启动所有服务
 docker-compose up -d
@@ -90,11 +107,14 @@ sleep 180
 ### 5. 初始化MySQL
 在终端里继续执行以下命令:
 ```bash
-cd initial_data && unzip init_mysql_db.sql.zip && cd ..
+cd initial_data && wget https://github.com/fengxu1211/generative-bi-using-rag/raw/demo_data/application/initial_data/init_mysql_db.sql.zip
+
+unzip init_mysql_db.sql.zip && cd ..
+
 docker exec nlq-mysql sh -c "mysql -u root -ppassword -D llm  < /opt/data/init_mysql_db.sql"
 ```
 
-### 6. 初始化OpenSearch  
+### 6. 初始化Amazon OpenSearch docker版本
 
 6.1 通过创建新索引来初始化示例数据的索引
 ```bash