An Application Programming Interface (API) paired with a web server that together expose the Plirono database to other Plirono applications and the world.
This is a Node.js project written in Typescript and built with the help of gulp. The API is served by an Express web server and is designed to connect to a MongoDB database (see #Environment for more). The database schema validation and connection with the database is achieved with mongoose. Project tests are run by Mocha against the Chai assertion library.
In order to launch Plirono API for production or development the following software must be installed on the machine:
- Node.js v6.9.2 or greater [Download] 1.1. If you already have another node version installed you can use the tool n to download additional node versions and easily switch between them
- Git [Download]
- MongoDB [Download]
To deploy in production copy and paste the following combined command in your Unix terminal:
[email protected]:maninak/plirono-api.git && cd plirono-api && npm i --only=production && npm build && cp ./env/prod.template.env ./env/.env && npm start
This will:
- clone the source code
- change into the source code directory
- install project dependencies
- build source code
- copy production environment variables (feel free to edit file
/env/.env
afterwards to suite your configuration needs) - launch Plirono API
You can get set-up for development by copy-pasting the following three commands in three (3) separate Unix terminals:
[email protected]:maninak/plirono-api.git && cd plirono-api && npm i && cp ./env/dev.template.env ./env/.env && npm run watch
This will:
- clone the source code
- change into the source code directory
- install project dependencies
- copy development environment variables (feel free to edit file
/env/.env
afterwards to suite your configuration needs) - launch watch task which upon each source code change will:
- delete
dist
folder that contains the resulting files of a previous build (this folder is NOT version-controlled) - run a linter against all
.ts
files, as per the rules specified intslint.json
- copy any assets from
src/assets
intodist/src/assets
- transpile all
.ts
file to.js
and.js.map
files and place into thedist
folder - run all tests found in the
test
folder
- delete
npm run localmongo
This will create and use a mongo-test
folder the project root and then launch a mongod
mongoDB demon that uses this folder as the db directory. This folder is NOT version-controlled.
npm run demon
This will launch the API web server using nodemon instead of node, with the environment variable DEBUG=prn-*
set by default to display all plirono-namespace debug messages and restart the API automatically upon each code change.
We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history. But also, we use the git commit messages to automatically generate the change log.
You can read more about the git commit guidelines in CONTRIBUTING.md
found in project root.
Upon npm install, a commit-msg
git hook is automatically installed that lints commit messages as per the rules defined in the CONTRIBUTING.md
.
patches:
git commit -a -m "fix(parsing): fix a bug in the parser"
features:
git commit -a -m "feat(parser): implement new parser \o/"
breaking changes:
git commit -a -m "feat(new-parser): introduce a new parsing library
BREAKING CHANGE: new library does not support foo-construct"
other changes:
You decide, e.g., docs, chore, etc.
git commit -a -m "docs: fixed up the docs a bit"
We use git flow (with default settings) to create feature, bugfix, etc branches.
Git flow can be practiced manually, but to make your life easy it's best to use automated tools that support it like GitKraken or a command-line tool.
Because of the fact that git commit messages are structured, versioning is done automatically using conventional-changelog
.
Running npm run release
in your terminal will get the latest available develop, scan its commits, bump bugfix or minor (or none) version number in package.json
depending on whether there are new features or not, update the CHANGELOG.md
file with the latest changes since last release and merge everything locally in the lastest available master. It then also applies a git-tag with the version number.
If you feel it is needed feel free to make corrections/additions by amending the master commit. If everything looks good, push the master branch upstream with the command
git checkout master && git push --follow-tags origin master
The filepackage.json
found in root directory contains many useful scripts executed from the teminal with the format npm run <script_name>
.
Here is a brief description of what each does:
postinstall
is called automatically upon eachnpm install
command and is hooked to a custom script. This script is useful to enforce repository state that all other tools cannot (e.g. install git hooks, apply simple edits on dependencies' source code using sed etc).,localmongo
see section Terminal 2start
launches the API web server (must have been built first)demon
see section Terminal 3watch
see (6) in section Terminal 1build
builds a production version of the app from source intodist
folderbuild-dev
builds a development version of the app from source intodist
folder, including javascript source mapsrelease
see section Release Versioningclean
deletesdist
folderpurge
deletes everything that isn't tracked by git or is ignored by git (useful to fall back to git clone state)
Upon launch, the API looks for the file .env
inside the env/
folder from which to load environment variables. If none is found, then the application falls back to using hardcoded development values as they exist in the template file env/dev.template.env
. There is also a suggested production configuration template found in env/prod.template.env
.
Contrary to the template files, the env/.env
file (if you create one) is NOT version-controlled.
- a preconfigured
.gitconfig
with useful git aliases and scripts - nifty Visual Studio Code settings
- helpful Visual Studio Code plugin set you can import using this vscode plugin