Skip to content

deploymentGuide.md

Latest commit

 

History

History
306 lines (237 loc) · 10.8 KB

deploymentGuide.md

File metadata and controls

306 lines (237 loc) · 10.8 KB

Deployment Guide

Table of Contents

Requirements

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

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.

Docker must also be running for the deployment to work.

Enable Models in Bedrock

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

Then click on "Modify model access":

Finally, enable the relevant models, click next and on the next page click submit. Amazon Titan Embeddings V2 and Meta Llama 3 70B Instruct are required for this project.

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>/Digital-Strategy-Assistant.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 Digital-Strategy-Assistant

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 "DSA-owner-name" \
    --value "<YOUR-GITHUB-USERNAME>" \
    --type String \
    --profile <YOUR-PROFILE-NAME>
Windows CMD 
aws ssm put-parameter ^
    --name "DSA-owner-name" ^
    --value "<YOUR-GITHUB-USERNAME>" ^
    --type String ^
    --profile <YOUR-PROFILE-NAME>
PowerShell 
aws ssm put-parameter `
    --name "DSA-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 DSASecrets \
    --secret-string "{\"DB_Username\":\"<YOUR-DB-USERNAME>\"}"\
    --profile <your-profile-name>
Windows CMD 
aws secretsmanager create-secret ^
    --name DSASecrets ^
    --secret-string "{\"DB_Username\":\"<YOUR-DB-USERNAME>\"}"^
    --profile <your-profile-name>
PowerShell 
aws secretsmanager create-secret `
    --name DSASecrets `
    --secret-string "{\"DB_Username\":\"<YOUR-DB-USERNAME>\"}"`
    --profile <your-profile-name>

 

For example,

aws secretsmanager create-secret \
    --name DSASecrets \
    --secret-string '{\"DB_Username\":\"DSASecrets\"}'\
    --profile <your-profile-name>
Note: No special characters are allowed in the secret value.

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 "/DSA/AllowedEmailDomains" \
    --value "<YOUR-ALLOWED-EMAIL-DOMAIN-LIST>" \
    --type SecureString \
    --profile <YOUR-PROFILE-NAME>
Windows CMD 
aws ssm put-parameter ^
    --name "/DSA/AllowedEmailDomains" ^
    --value "<YOUR-ALLOWED-EMAIL-DOMAIN-LIST>" ^
    --type SecureString ^
    --profile <YOUR-PROFILE-NAME>
PowerShell 
aws ssm put-parameter `
    --name "/DSA/AllowedEmailDomains" `
    --value "<YOUR-ALLOWED-EMAIL-DOMAIN-LIST>" `
    --type SecureString `
    --profile <YOUR-PROFILE-NAME>

 

For example,

aws ssm put-parameter \
    --name "/DSA/AllowedEmailDomains" \
    --value "gmail.com,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.

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=Digital-Strategy-Assistant \
 --context StackPrefix=<your-stack-prefix> \
 --profile <your-profile-name>

For example:

cdk deploy --all --parameters DigitalStrategyAssistant-Amplify:githubRepoName=Digital-Strategy-Assistant --context StackPrefix=DigitalStrategyAssistant --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.