The API is utilized for the Boom web, mobile, POS tablet, and admin portal projects.
This project is split into two folders:
functions
= The Firebase cloud functions project. Mainly used for managing user account roles and setting roles as custom claims for their web tokens.
api
= The main API folder. This is where our Loopback project is located.
The production environment is currently set to run in Node version 10.16.0
.
- Install Node version manager. This allows you to switch Node versions as needed. MacOS/Linux version is here. Windows version is here
- Install the Loopback CLI. This gives you convenience commands for performing certain tasks in the Loopback project.
You should always branch off the develop
branch. As this is the branch that has the most current work.
You'll need the .env
file for this project to get our local configuration keys/settings. This file must be placed inside the api
directory.
You'll need these to allow our project to make Firebase calls. These are also placed inside the api
directory.
service-account-file--dev.json
service-account-file--qa.json
service-account-file--migration-source.json
There's several options for connecting the project to a MongoDB database, by editing the .env file's DB_ENV
variable to one of the following:
local
= This points you to a dev database running on our AWS environment. Your ip address must be whitelisted to get access to this database.
docker
= This points you to the database that has been locally provisioned to you via Docker, if you choose to run the Docker scripts that come with the project (more on that below).
To enable redis editing the .env file's REDIS_ENABLED
set it to true (by default it is set to false
)
REDIS_HOST
default one is 127.0.0.1
for Docker change it to redis
(more on that below).
REDIS_PORT
default one is 6379
live
= This is the live production database config. Due to security restrictions, this configuration will not be able to connect to the database except within an AWS environment that is a member of the virtual private cloud running the database servers. So this is not an option for local development.
local-prod
= This configuration can connect to the live production database. This requires that your local computer can ssh into the bastion host server, that will allow you to connect via port forwarding, into the database.
See documentation on how to connect for Windows and Mac
This option is only to be done when you must gain access to the production database, but in most cases you should not do this.
By default, our .env
file will connect you to the remote dev database, by setting the DB_ENV
variable to local
.
In the app
directory, install the node dependencies by issuing the npm install
command.
Issue npm start
command to run the project. Or if you'd like to restart the server when making an update to a file in the project, run the npm run start:watch
command.
Application will be available in http://localhost:3000
If you'd like to use Docker to provision a database for you. You can run these build commands below. (Some Environment variables are changed internally check below)
npm run docker:up
= This will build the Docker containers necessary to run the API via Docker.
npm run docker:db:seed
= Run this only the first time you are building the docker container.
The container will remain running even if you close your project. If you'd like to stop the container you can issue this command:
npm run docker:down
If you have added new dependencies to the project, or you want to stop and delete the container you created, you can run this command:
npm run docker:down:clean
You can then re-build the containers with the up command mentioned earlier.
Application will be available in http://localhost:3000
DB_ENV
is set to docker
as explained earlier
REDIS_HOST
is set to redis
REDIS_ENABLED
is set to true
(remember to add it to to the .env file)
To use the .env files remove these values from docker-compose.yml and the ones set on .env file will be used
The .env file sets NODE_ENV
= 'live'. This is because in the AWS environment, we can't use 'production' as usual, because this prevents the server from installing devDependencies in package.json which are needed for our project
The Elastic Beanstalk environments requires that we set the PORT
environment variable to 8081
View API explorer: http://localhost:3000
This app is configured for deployment to an Elastic Beanstalk environment. To set up this project to deploy to Elastic Beanstalk on your machine:
- Install Elastic Beanstalk CLI
- Initialize your project to use Elastic Beanstalk
eb init
- Select
us-west-2
region - You will be prompted to add necessary IAM access id and secret key
- Select the
Boom Platform
application - Select the
BoomPlatformAPI--staging
environment
You should now be able to deploy the application to staging with:
npm run deploy
This deployment uploads the source files, and will build the project on the remote server using the build scripts in package.json.
When running deploy, we check the typescript fields for errors using tsc and eslint, if all goes ok we update the package version and upload the changes of version to bitbucket. To avoid updating the version run npm run deploy:noUpdateVersion
in order to run : npm run start:docker