Skip to content

Latest commit

 

History

History
185 lines (114 loc) · 7.49 KB

DEVELOPER.md

File metadata and controls

185 lines (114 loc) · 7.49 KB

Developer Guide

This page is intended for developers who want to contribute to the project. This is the backend engine of Launch Pad. We use AWS CDK to deploy the backend infrastructure.

Prerequisites

AWS Getting Started

Check Resources for a list of links, guides, etc contributors have found helpful for this project.

Setup

  1. Clone the repo

    git clone https://github.com/ubclaunchpad/StarPort.git

Installation

  1. Check you have node and npm installed. you can run the following to see if they are installed

    node -v
npm -v

    if not installed refer to their docs for installation steps: node, npm

  2. install Typescript (optionally) globally by running npm install -g typescript

  3. install AWS CDK npm install -g aws-cdk. verify by running cdk --version

  4. install AWS SAM npm install -g aws-sam-local. verify by running sam --version if you intend to run the project locally

  5. install dependencies:

    cd starport
npm install

Developing

To start developing after you run the setup steps you should do the following.

  1. since our api is connected to a database to run it fully we recommend setting up a MySQL server on your machine or if familiar with Docker, on there.

We are using PlanetScale as our database provider. You can create a free account and create a database. You can then create a user and get the credentials.

After setting up your database, store your db credentials in a env.local file at the source directory (during deployment we will use .env that has the cloud database credentials)

An example of how the file will look

DATABASE_HOST=<your-db-host>
DATABASE_USERNAME=<your-db-username>
DATABASE_PASSWORD=<your-db-password>
DATABASE_URL=<your-db-url>
ENVIRONMENT=dev

you will also need to seyt your CDK environment variables. You can do this by creating a cdk.context.json file at the root of the project. An example of how the file will look

add the following to the .env file

CDK_TEST_ACCOUNT=<test-account-id>
CDK_TEST_REGION=<test-region>
CDK_DEFAULT_ACCOUNT=<your-account-id>
CDK_DEFAULT_REGION=<your-region>

Tip: lots of good resources to set up on your laptop quickly, and to verify it's connected first try connecting to it either via your terminal or with a client like Workbench

Following steps varies depending on how you want to run the project

Test-driven Development/Writing tests

you can easily write tests for each of the lambda groups in their test folder. you can run the tests by running

npm run test:src

if you're writing tests for the deployment stacks too you can just do npm run test

Developing with CDK

Cdk is a toolkit for AWS cloudformation. after all our code we want to tell AWS what is what and how things are related. Assuming you have looked up basic AWS CDK resources you can run the follwing to build your assets

npm run build
cdk synth

first transpiles our .ts and the next, synthesizes our stacks and constructs (to make it ready for deployment)

Local Emulation

To test your lambda functions or API integrations locally, AWS SAM helps here. Sam emulates a porduction environment that AWS would have used to run our project. SAM is a framework for building serverless applications on AWS. It provides a Lambda-like execution environment that lets you locally build, test, and debug applications defined by SAM templates.

To do this, you need to first install SAM and Docker.

check you have them installed:

docker version
sam --version

Running Lambdas Locally

Tip: check package.json for some frequently used scripts related to this

You can test your functions in two ways:

  1. Invoke your lambda function based on a specific predefined event (e.g. an event.json file)

    • This will run your lambda function locally and pass in the event as the input and return the output of the function. This is useful for testing your lambdas with testing frameworks like Mocha
    • To run your lambda function locally, run sam local invoke <function-name> -e <event.json>
    • To run your lambda function locally with a debugger, run sam local invoke <function-name> -e <event.json> -d 5858

  2. Run your lambda function locally as an API

    We recommend a test-driven approach to developing your functions. So use this method sparingly as it can take up your battery if you are running it for a long time. It's a good apporach to do your holistic testing before deploying your functions to AWS.

    • To run your lambda function locally as an API, run sam local start-api
    • To run your lambda function locally as an API with a debugger, run sam local start-api -d 5858

Note: invoking just runs your function and exits. great for integration/e2e testing. Second one keep the function running

Running APIs Locally

Similar to locally testing your lambdas, you can also run and test your APIs locally. This is helpful when you have a few lambdas or stepfunctions, etc integrated to your API and you want to test the whole flow.

  • To run your API locally, run sam local start-api
  • To run your API locally with a debugger, run sam local start-api -d 5858

Note: For all the sam scripts to run the correct stack, you need to provide the template cdk generates

so before emulation you should run

npm run build
cdk synth

and then with all your stacks you should provide the relative path to the stack's template - check package.json for examples

Running APIs with hot reload (capable on windows machine)

We have integrated build-start commands into one bash script.

  • To run your API locally, run npm run test:api [stack] [port] [docker-option].
  • [stack] field will be the full stack name under folder
  • [port] field will be the port the service will listen on
  • [docker-option] field will be either EAGER or LAZY

Note: [] fields are optional, and if is null the script will just use default setting (stack=wiki-template.stack; port=8000; docker-option=LAZY)

Note: when trying to end the process using ctrl+c, if it stuck just kill the terminal.

Deployment

Refer to the AWS deployment guide for more information. However, we only allow cloud deployment via the CI/CD pipeline. So you should not be deploying to AWS manually; in fact you should not have the AWS credentials to do so or we have set up something wrong :).

Background

The repository offers/implementes a lot of different things. Here is a briefly overview:

  • AWS CDK is used for cloud deployment. Everything in the project gets bundled together with CDK. So CDK is responsible for creating all our resources. APIs, Database, running our scripts and so on.
    • we test our deployment process with Jest (A testing framework)
  • The APIs are based on a serverless model. everything in the src folder serves as the source code. With CDK and the AWS Lambda we create our APIs (if familiar with Express, it's same end-result but different implementation)
    • we test our API source code locally by using Jest
    • Additonally we use AWS SAM to live-test our api (lambdas + cdk integration)
  • The database is a MySQL flavour of SQL. We use Aurora Serverless to adapt to flexible traffic.
    • We keep our database identicial throughout development by running migration scripts