Table of Contents
- Set up VS Code
- Set up git-secrets hooks
- Set up LTI tool
- MongoDB installation and setup
- Start up the app
- Test it out
- Documentation
- Download and install VS Code: https://code.visualstudio.com/
- Install ESLint package: https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint
- Install ESLint rules:
npx install-peerdeps --global eslint-config-wesbos
To prevent us from accidentally committing secrets, we will install the git-secrets hooks.
-
Install git-secrets locally on your machine. See instructions for your platform here.
-
Set up git-secrets for this repo
cd
into the repo- Run
git secrets --install
-
Configure git-secrets by running the following commands:
git secrets --register-aws
git secrets --add 'SECRET(\s|[a-zA-Z\_])*=\s*.+'
These rules will prevent any variables prefixed with SECRET_
from being committed with a value filled in.
-
Start up your local Moodle on Docker, then log in as admin
-
Go to Site administration → Plugins → Activity modules → External tool → Manage tools
-
Click on "configure a tool manually"
-
Configure the following:
- Tool settings:
- Tool name: (Anything)
- Tool URL: http://localhost:8080
- LTI version: LTI 1.3
- Public key type: RSA key
- Initiate login URL: http://localhost:8080/login
- Redirection URI(s): http://localhost:8080
- Services:
- IMS LTI Assignment and Grade Services: Use this service for grade sync and column management
- IMS LTI Names and Role Provisioning: Use this service to retrieve members' information as per privacy settings
- Tool Settings: Use this service
- Privacy:
- Share launcher's name with tool: Always
- Share launcher's email with tool: Always
- Accept grades from the tool: Always
- Tool settings:
-
Click "Save changes"
-
Under "Tools", find the LTI app you just created and click on the "View configurations" icon (first icon, next to gear)
-
Copy Client ID value into the SECRET_PLATFORM_CLIENTID variable in .env (created below in Start up the app, Step 1)
- Install MongoDB: https://docs.mongodb.com/manual/administration/install-community/
- Helpful to install MongoDB Compass to ensure your database is running correctly: https://www.mongodb.com/try/download/compass
- Follow the steps below for setting MongoDB for development
In order to use MongoDB transactions, we need to configure our local MongoDB development instance with a replica set.
If you are on macOS, you should only need to do this configuration once. If you are on Ubuntu, you may need to start mongod manually every time after boot.
(The following steps were tested on macOS Catalina 10.15.6.)
-
Make sure MongoDB isn't currently running. (Running
mongo
should give an error)- If you are doing this setup for the first time, stop mongod. https://docs.mongodb.com/manual/tutorial/install-mongodb-on-ubuntu/
- If you have already done this setup before, and you see mongod running on computer boot, it means that you have autostart enabled
- In this case, do step 3 below to make sure you do have replica set. Stop mongod and continue with step 2 only if you don't see any replica set
-
Start MongoDB by running
mongod --port 27017 --dbpath /usr/local/var/mongodb --logpath /usr/local/var/log/mongodb/mongo.log --replSet rs0 --bind_ip localhost
- The paths for
--dbpath
and--logpath
might vary depending your system- Look for the paths in the MongoDB configuration file
- The
--dbpath
must be specified as such on macOS Catalina or newer because Catalina has made the root volume read-only, so the default/data/db
path does not work - The argument after
--replSet
should match theDB_REPLSET
.env variable
- The paths for
-
Enter the MongoDB shell by running
mongo
- Inside the mongo shell, run
rs.initiate()
to create a replica set - Verify that there is a replica set by running
rs.status()
. Runningrs.status().set
gives you the name of the replica set
- Inside the mongo shell, run
- If you don't have migrate-mongo package installed globally, run
yarn global add migrate-mongo
- Inside project directory, run
migrate-mongo up
to get create all the needed collections - Run all scripts under src/server/jobs/update-xxx.js by running
node src/server/jobs/update-xxx.js
- These scripts must be run with a CCLE IP address. Use the CCLE VPN if you are off campus
update-bcast.js
takes in 1 command-line parameter called 'term'- For example, run
node src/server/jobs/update-bcast.js 20S
to update Bruincast records for term 20S
- For example, run
To create or modify the mongo migration script, see documentation at https://github.com/seppevs/migrate-mongo/#creating-a-new-migration-script.
-
Copy .env.dist to a local .env file. There are some empty secret fields in .env.dist. Ask Rex for the secrets.
-
Set LTI_KEY to any random string, and DB_DATABASE to whatever you'd like
-
(Optional) Comment out DEBUG if you do not want to see the LTI provider debugging messages
-
Start app:
yarn
yarn dev
-
On initial load, the app will display the public key in the terminal
-
Copy the key, and remember to remove the
[0]
characters from the start of each row of the key, and include the BEGIN/END PUBLIC KEY lines -
Go to Site administration → Plugins → Activity modules → External tool → Manage tools again, and click on the gear icon on the LTI external tool
-
Paste the public key you just copied (with
[0]
removed) into 'Public key'
- Go to a course site
- Turn editing on and click "Add activity or resource", choose External tool, enter any name, choose your LTI tool from Preconfigured tool, and then click "Save changes"
- You should see your tool embedded in the site and the app should load
- LTIjs: https://cvmcosta.me/ltijs/#/provider
- Instructure UI: https://instructure.design/
- Migrate-mongo: https://www.npmjs.com/package/migrate-mongo
- Jest: https://jestjs.io/
- UCLA API: https://kb.sait.ucla.edu/display/KB/API+Knowledgebase
- Download the CLI: https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html
- Run
aws configure
in your terminal- Go to "My Security Credentials" for the access and secret key
us-west-2
as the default region- https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html for more information
Make sure "Oregon" (us-west-2) is the selected region in the AWS Console before performing any of the next steps.
- Go to the Elastic Container Registry in the AWS Console
- Create a private repository
- After creating the repository, click on the name to view the images (will be empty)
- Click on the "View push commands" button to view the 4 commands to push images to the repository
- After pushing an image to the repo, move on
This will need to be repeated for each service listed in the Docker Compose file (Nodeserver and Nginx).
To utilize elastic IP with ECS Fargate, we need to use a NLB. Visit https://aws.amazon.com/premiumsupport/knowledge-center/ecs-fargate-static-elastic-ip-address/ for directions.
- Go to AWS ECS (Elastic Container Service)
- Create a cluster
- Select "Networking Only" for the cluster template
- Enter a name
- Go to Task Defintions on the AWS ECS side menu
- Create new tasks definition
- Choose Fargate
- Enter a name, memory, and CPU size
- Click on Add Container
- Add the container for the nodeserver (Image URI can be found in the ECR)
- Enter port 8080 for the Port Mappings
- Add the container for the nginx server (Image URI can be found in the ECR)
- Enter port 80 for the Port Mappings
- Enter port 443 (SSL) for the Port Mappings
- Add the container for the nodeserver (Image URI can be found in the ECR)
- Create task definition
Using the new task definition, we can now run the app on our cluster.
- Go to Clusters in the AWS ECS side menu
- Click on the cluster that was previously created
- Click on Create under the Services tab
- Under launch type, click Fargate
- Under task defintion, select the task that was just created
- Enter a service name
- Enter 1 for number of tasks
- Choose the first option for Cluster VPC and Subnets
- Edit the Security Group to allow traffic over HTTPS
- Select the Network Load Balancer
The service should now be running.
Once the task is running, you can now connect it to the CCLE LTI tool.
- Under the Task tab for the running service, click on the running task
- Under Network, copy and paste the Public IP
- Go to the External Tool Configuration on CCLE
- Copy and paste the IP with the port for Tool URL, Initiate login URL, and Redirection URI(s)
- It will be of the form
https://<Public IP>
- It will be of the form
- To avoid CORS issues, switch Default launch container to New Window
- Save changes
- Push the new image to the repository (these can be found under "View push commands" in the AWS ECR repo)
- Retrieve login token -
aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin <AccountId>.dkr.ecr.us-west-2.amazonaws.com
- Build image -
docker-compose build
- Tag and Push Image -
docker-compose push
- This will tag and push from the image field listed in the Docker Compose file
- Retrieve login token -
- Update the cluster service to use the new image -
aws ecs update-service --cluster <Cluster Name> --service <Service Name> --force-new-deployment
- If Auto-Assign IP is on, the Public IP will be changed and need to be updated in the CCLE tool settings
The Cluster will stop the old task once the newer version is up and running.
This can also be done manually in the AWS console if the new image has a different tag.
- Click on the task definition
- Click on Create new revision
- Update the container defintion with the new image tag
- Update the task defintion revision
- Go to the ECS Cluster
- Click on the Service and hit Update
- Choose the latest revision for the task defintion
The Service will now have the latest image of the app. The previous task will need to be stopped.
1, Create an AWS account. Please ask Daniel Tran for it.
2, Configure AWS CLI. https://github.com/ucla/lti-media-resources/blob/master/.env.dist#L11
3, Update local .env file with AWS_ACCOUNT_ID here. https://github.com/ucla/lti-media-resources/blob/master/.env.dist#L11 You can find the account ID by logging into aws console.
4, Add certs folder under lti-media-resources/nginx-conf.
5, Run deploy.sh under lti-media-resources. Command: ./deploy.sh --id=<AWS_ACCOUNT_ID> --env=<PROD|STAGE|TEST>
6, After a successful deployment, a json file will be produced. Verify it says status:active
7, We can also verify an instance’s status in this way:
Log in to AWS console. https://aws.amazon.com/console/
Services > Containers > Elastic Container Service.
Click on lti-clusters.
We can see the status of all three instances here.
There are AWS ECS enviroments for PROD, STAGE, and TEST.
Use the deploy script ./deploy.sh --id=<AWS_ACCOUNT_ID> --env=<PROD|STAGE|TEST>
to push the latest image to the respective environment.
The Nginx server and Dockerfile assume that the SSL public and private keys for the different environments are located in the nginx-conf/certs/<prod|stage|test>
directory.
The file name for the keys should be mediaresources-<ENV>.ccle.ucla.edu.cert.cer
and mediaresources-<ENV>.ccle.ucla.edu.key
respectively.