Skip to content

Latest commit

 

History

History
374 lines (262 loc) · 12.5 KB

deploymentGuide.md

File metadata and controls

374 lines (262 loc) · 12.5 KB

Deployment Guide

Table of Contents

Requirements

Before you deploy, you must have the following installed on your device:

Request Higher Bedrock LLM Invocation Quotas

For optimal scoring performance, it is recommended to request higher invocation quotas for Bedrock LLM models before deployment. The default quotas may be insufficient for processing large datasets or concurrent scoring operations.

To request quota increases:

  1. Navigate to the AWS Service Quotas console in your AWS account
  2. Search for "Bedrock" in the service quotas
  3. Select the relevant LLM models you plan to use (e.g., Meta Llama 3 70B Instruct, Mistral Large 2402)
  4. Request quota increases for "Requests per minute" based on your expected usage
  5. Submit the quota increase request and wait for AWS approval (this can take 24-48 hours)

Note: Consider your expected concurrent users and document processing volume when requesting quota increases. Higher quotas ensure smoother scoring operations without throttling.

Pre-Deployment

Create GitHub Personal Access Token

To deploy this solution, you will need to generate a GitHub personal access token. Please visit here for detailed instruction to create a personal access token.

Note: when selecting the scopes to grant the token (step 8 of the instruction), make sure you select repo scope.

Once you create a token, please note down its value as you will use it later in the deployment process.

Enable Models in Bedrock

First, navigate to Amazon Bedrock in the AWS Console. From the home page, click on model access under Bedrock configurations: Bedrock Home

Then click on "Modify model access": Modify Models

Finally, enable the relevant models, click next and on the next page click submit. The following models are required for this project:

  • Amazon Titan Embeddings V2 (for document embeddings)
  • Meta Llama 3 70B Instruct (text generation model)
  • Meta Llama 3 8B Instruct (text generation model)
  • Mistral Large 2402 (text generation model)
  • Amazon Titan Text Express V1 (text generation model)

Enable Models

The relevant models are now enabled in Bedrock.

Deployment

Step 1: Fork & Clone The Repository

First, you need to fork the repository. To create a fork, navigate to the main branch of this repository. Then, in the top-right corner, click Fork.

You will be directed to the page where you can customize owner, repository name, etc, but you do not have to change any option. Simply click Create fork in the bottom right corner.

Now let's clone the GitHub repository onto your machine. To do this:

  1. Create a folder on your computer to contain the project code.
  2. For an Apple computer, open Terminal. If on a Windows machine, open Command Prompt or Windows Terminal. Enter into the folder you made using the command cd path/to/folder. To find the path to a folder on a Mac, right click on the folder and press Get Info, then select the whole text found under Where: and copy with ⌘C. On Windows (not WSL), enter into the folder on File Explorer and click on the path box (located to the left of the sch bar), then copy the whole text that shows up.
  3. Clone the GitHub repository by entering the following command. Be sure to replace <YOUR-GITHUB-USERNAME> with your own username.
git clone https://github.com/<YOUR-GITHUB-USERNAME>/Research-Data-Insights.git

The code should now be in the folder you created. Navigate into the root folder containing the entire codebase by running the command:

cd Research-Data-Insights

Install Dependencies

Go into the cdk folder which can be done with the following command:

cd cdk

Now that you are in the cdk directory, install the core dependencies with the following command:

npm install

Go into the frontend folder which can be done with the following command:

cd ../frontend

Now that you are in the frontend directory, install the core dependencies with the following command:

npm install

Step 2: Upload Secrets

You would have to supply your GitHub personal access token you created earlier when deploying the solution. Run the following command and ensure you replace <YOUR-GITHUB-TOKEN> and <YOUR-PROFILE-NAME> with your actual GitHub token and the appropriate AWS profile name.

macOS
aws secretsmanager create-secret \
    --name github-personal-access-token \
    --secret-string '{"my-github-token": "<YOUR-GITHUB-TOKEN>"}' \
    --profile <YOUR-PROFILE-NAME>
Windows CMD
aws secretsmanager create-secret ^
    --name github-personal-access-token ^
    --secret-string "{\"my-github-token\": \"<YOUR-GITHUB-TOKEN>\"}" ^
    --profile <YOUR-PROFILE-NAME>
PowerShell
aws secretsmanager create-secret `
    --name github-personal-access-token `
    --secret-string '{"my-github-token": "<YOUR-GITHUB-TOKEN>"}' `
    --profile <YOUR-PROFILE-NAME>

 

Moreover, you will need to upload your github username to Amazon SSM Parameter Store. You can do so by running the following command. Make sure you replace <YOUR-GITHUB-USERNAME> and <YOUR-PROFILE-NAME> with your actual username and the appropriate AWS profile name.

macOS
aws ssm put-parameter \
    --name "rdi-owner-name" \
    --value "<YOUR-GITHUB-USERNAME>" \
    --type String \
    --profile <YOUR-PROFILE-NAME>
Windows CMD
aws ssm put-parameter ^
    --name "rdi-owner-name" ^
    --value "<YOUR-GITHUB-USERNAME>" ^
    --type String ^
    --profile <YOUR-PROFILE-NAME>
PowerShell
aws ssm put-parameter `
    --name "rdi-owner-name" `
    --value "<YOUR-GITHUB-USERNAME>" `
    --type String `
    --profile <YOUR-PROFILE-NAME>

 

You would have to supply a custom database username when deploying the solution to increase security. Run the following command and ensure you replace <YOUR-DB-USERNAME> with the custom name of your choice.

macOS
aws secretsmanager create-secret \
    --name RDISecrets \
    --secret-string "{\"DB_Username\":\"<YOUR-DB-USERNAME>\"}"
    --profile <your-profile-name>
Windows CMD
aws secretsmanager create-secret ^
    --name RDISecrets ^
    --secret-string "{\"DB_Username\":\"<YOUR-DB-USERNAME>\"}"^
    --profile <your-profile-name>
PowerShell
aws secretsmanager create-secret `
    --name RDISecrets `
    --secret-string "{\"DB_Username\":\"<YOUR-DB-USERNAME>\"}"`
    --profile <your-profile-name>

 

For example,

aws secretsmanager create-secret --name RDISecrets --secret-string "{\"DB_Username\":\"RDIDatabaseUser\"}" --profile <your-profile-name>

Finally, in order to restrict user sign up to specific email domains, you will need to upload a comma separated list of allowed email domains to Amazon SSM Parameter Store. You can do so by running the following command. Make sure you replace <YOUR-ALLOWED-EMAIL-DOMAIN-LIST> and <YOUR-PROFILE-NAME> with your actual list and the appropriate AWS profile name.

macOS
aws ssm put-parameter \
    --name "/RDI/AllowedEmailDomains" \
    --value "<YOUR-ALLOWED-EMAIL-DOMAIN-LIST>" \
    --type SecureString \
    --profile <YOUR-PROFILE-NAME>
Windows CMD
aws ssm put-parameter ^
    --name "/RDI/AllowedEmailDomains" ^
    --value "<YOUR-ALLOWED-EMAIL-DOMAIN-LIST>" ^
    --type SecureString ^
    --profile <YOUR-PROFILE-NAME>
PowerShell
aws ssm put-parameter `
    --name "/RDI/AllowedEmailDomains" `
    --value "<YOUR-ALLOWED-EMAIL-DOMAIN-LIST>" `
    --type SecureString `
    --profile <YOUR-PROFILE-NAME>

 

For example, an email domain list we reccommend for this specific project is:

aws ssm put-parameter \
    --name "/RDI/AllowedEmailDomains" \
    --value "gmail.com,ubc.ca,student.ubc.ca" \
    --type SecureString \
    --profile <YOUR-PROFILE-NAME>

Step 3: CDK Deployment

It's time to set up everything that goes on behind the scenes! For more information on how the backend works, feel free to refer to the Architecture Deep Dive, but an understanding of the backend is not necessary for deployment.

Open a terminal in the /cdk directory.

Download Requirements: Install requirements with npm by running npm install command.

Initialize the CDK stack(required only if you have not deployed any resources with CDK in this region before). Please replace <your-profile-name> with the appropriate AWS profile used earlier.

cdk synth --profile <your-profile-name>
cdk bootstrap aws://<YOUR_AWS_ACCOUNT_ID>/<YOUR_ACCOUNT_REGION> --profile <your-profile-name>

Deploy CDK stack You may run the following command to deploy the stacks all at once. Again, replace <your-profile-name> with the appropriate AWS profile used earlier. Also replace <your-stack-prefix> with the appropriate stack prefix.

The stack prefix will be prefixed onto the physical names of the resources created during deployment. The environment parameter specifies the deployment environment (dev, test, prod), and the version parameter indicates the application version being deployed.

If you have trouble running the above command, try removing all the \ and run it in one line.

cdk deploy --all \
 --parameters <your-stack-prefix>-Amplify:githubRepoName=Research-Data-Insights \
 --context StackPrefix=<your-stack-prefix> \
 --context environment=dev \
 --context version=1.2.0 \
 --context githubRepo=Research-Data-Insights \
 --profile <your-profile-name>

For example:

cdk deploy --all --parameters ResearchDataInsights-Amplify:githubRepoName=Research-Data-Insights --context StackPrefix=ResearchDataInsights --context environment=dev --context version=1.2.0 --context githubRepo=Research-Data-Insights --profile <your-profile-name>

Post-Deployment

Step 1: Build AWS Amplify App

  1. Log in to AWS console, and navigate to AWS Amplify. You can do so by typing Amplify in the search bar at the top.
  2. From All apps, click <stack-prefix>-Amplify-admin.
  3. Then click main under branches
  4. Click run job and wait for the build to complete.
  5. You now have access to the Amplify App ID and the public domain name to use the web app.
  6. From All apps, click <stack-prefix>-Amplify-public and repeat steps 3-5.

Step 2: Visit Web App

You can now navigate to the web app URL to see your application in action.

Cleanup

Taking down the deployed stack

To take down the deployed stack for a fresh redeployment in the future, navigate to AWS Cloudformation on the AWS Console, click on the stack and hit Delete.

Please wait for the stacks in each step to be properly deleted before deleting the stack downstream.

Also make sure to delete secrets in Secrets Manager.