sciens.io v0.1.0

sciensio-api

Table of Contents

• Environment Variables
• Developing Locally with Docker
  • Bootstrapping Local Data
    • add-admin
    • add-org
  • Accessing Docker Services
• Developing with Hosted Services
• Unit Testing with Jest
• ES Lint
• Postman Scripts
• Heroku Deployment
• Security
  • Jwt Validation
  • User Validation
  • User Authorization

Environment Variables

The dotenv package is used to read variables from a local .env file as environment variables.

• Make a copy of .env.ex: cp .env.ex .env
• Choose how you want to work:
  • Fully local with docker-compose (Preferred)
  • Against hosted services

Note: all .env files are git-ignored so it is safe to put sensitive data in your local .env file but NOT the .env.ex file.

Developing Locally with Docker

Using docker-compose you can easily install and run the requisite services in containers to get an isolated set of services that can be created and destroyed at will.

See docker-compose.yml for a list of the services running in docker.

• Install docker-compose (https://docs.docker.com/compose/install/)
• Ensure docker is running
• run docker-compose up from the root of the repo

Bootstrapping Local Data

After starting the container(s) for the first time you need to bootstrap the database as well.

• Add your auth0 user id and email to docker-bootstrap.sh
• run ./docker-bootstrap.sh

You can run individual scripts for one-off data insertion or add additional lines to docker-bootstrap.sh for data that should alway be present.

add-admin

Adds a user will full system administrator rights

node scripts/add-admin --userId=[auth0 user id] --email=[email address]

add-org

Adds an empty org

node scripts/add-org --orgId=[unique org id] --name=[org name]

Accessing Docker Services

• Mongo: http://localhost:8081 (no creds)
• Rabbit: http://localhost:15672 (rabbitmq/rabbitmq)

Note: A full list can be found by looking at docker-compose.yml

Developing with Hosted Services

Note: Running docker-comopse is the preferred method for local developmet

To run against services that are not hosted in docker (or on default ports locally) you can override environment variables using a .env file at the root of the repo.

• Edit your .env file with the necessary values
• Restart the application

You can find all possible values to override by looking in Heroku: sciensio-app > settings

Running the Application

The app can be run with or without nodemon to watch for file change and auto recomplie

• With nodemon: npm run dev or yarn dev (preferred for local dev)
• Without nodemon: npm start or yarn start (what Heroku runs)

Unit Testing with Jest

All test are written using the Jest testing framework from Facebook (https://facebook.github.io/jest/).

Jest supports both auto mocks and manual mocks. We use both and its worth understand the differences: https://facebook.github.io/jest/docs/en/manual-mocks.html#content

• To run tests: npm run test or yarn test

Notes on structure

• Tests are located next to the class they are testing
• Manual mocks are located in a folder named __mocks__ relative to the module they are mocking

ES Lint

ES lint is enabled and configured via .eslintrc.json. Currently it is only run manually.

• To run linter: npm run lint or yarn lint

Postman Scripts

The Postman collection and environment files are located at /scripts/postman.

• Import Collection Sciensio.postman_collection.json
• Import Environments
  • Sciensio-local.postman_environment.json
  • Sciensio.postman_environment.json
• Set Environment Variables
  • login_email and login_password (social login only works via the UI)
  • orgId to whatever org you want execute api calls against

Note: The bearer_token variable will automatically get populated everytime you run the Auth/Login script assume the response is successful.

Heroku Deployment

The Heroku application is configured to automatically deploy on commits to github. For this reason, you should develop in the test branch and only merge to master when ready for the code to go live.

• The test branch deploys to the sciensio-api-test app
• The master branch deploys to the sciensio-api app

Security

Authentication and Authorization are handled in the API via JWT bearer tokens. After obtaining a token, a call to the api can be made by adding the following header to any request:

Authorization: Bearer [token]

Token contents can be viewed by pasting into https://jwt.io

The auth pipeline for a request is handled via multiple middlewares and is broken down as follows:

Jwt Validation

• Middleware: jwt-express (via npm)
• Validates:
  • Existence of Authorization header and bearer token
  • Token is a valid format
  • Token signature is valid
  • Token issuer is trusted
• Byproducts:
  • req.token now contains the parsed token

User Validation

• Middleware: user-middleware.js
• Validates:
  • User exists in app database
• Byproducts:
  • None if token is not present
  • 401 Unauthorized if user is not found
  • req.user now contains the valid user

User Authorization

• Middleware: scoped-middleware.js
• Validates:
  • User has required scope at either user or org level
• Byproducts:
  • 401 Unauthorized if user does not have required scope