sciens.io v0.1.0
sciensio-api
Table of Contents
- Environment Variables
- Developing Locally with Docker
- Developing with Hosted Services
- Unit Testing with Jest
- ES Lint
- Postman Scripts
- Heroku Deployment
- Security
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
- Fully local with
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
oryarn dev
(preferred for local dev) - Without nodemon:
npm start
oryarn 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
oryarn 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
oryarn 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
andlogin_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 theAuth/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 thesciensio-api-test
app - The
master
branch deploys to thesciensio-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
7 years ago