Skip to content

Development setup

Warning

These instructions are out of date. The information may no longer be accurate.

Requirements

This application requires an installation of Node.js and NPM compatible with v16.0.0 and v6.4.1, respectively. Most of the API will work with Node LTS version 12.

The package.json file documents the node dependancies required by this project. Running npm install in the terminal from the project root will install the dependencies. One dependency, hakai-upload-validator, will require that you first have read access to the hakai-upload-validator GitHub repository.

Installation and Configuration

Setting up the database seed

  • Many endpoints require the presence of specific tables for logging requests and errors. The easiest way to create these are to refer to the hakai-database repo docs and follow the instructions for generating the seed database with those tables.

To run a local version of the API service:

  • Clone the repo from github.com/HakaiInstitute/hakai-api

  • Create a .env file in the hakai-api directory with the same format as the .env.sample file. Fill in the values so that the app is properly configured

  • Authentication, workarea and organization 'auth-filters', and workarea checks for CTD and Solo uploading and annotating can be enabled or disabled when running the API locally. Set RUN_LOCAL_AUTH to 'true' or 'false' in .env file.

  • Install node requirements from package.json using npm install

  • Run the server with npm start

The API endpoints will now be available at http://localhost:8666. Tools like Postman are often useful for testing these endpoints. Running the project locally will enable you to access all endpoints without needing an authorization header.

The package.json file also contains scripts to run the project with PM2, which is a process manager for Node applications. PM2 watches the process and restarts it if it crashes. Using PM2, the API can run continuously as a background process.

To run the project using PM2, first install it globally with npm install -g pm2. Run npm run local or npm run start:local to start the API on your machine with PM2. You can check that the process is running using pm2 ls or pm2 m.

Matlab

The matlab service for converting rsk files to txt now lives in a docker container. Note, this container only works for non-M1 machines. See the docker-compose.yml for more info.

Testing

There are tests available for the RBR CTD cast detection, Solo cast detection, and the RBR parse script. These files are a combination of problem files, edge cases, and standard files to make sure any changes aren't breaking for previous cases. They can all be run at once with npm test, or run individually with detailed output using DEBUG=ctd npm run test:ctd or DEBUG=parse npm run test: parse.

There is a separate test suite under hakai-api/test that requires a connection to a database. To use locally, make sure you have a local docker database and api running that are congruent with the ' server' variable (localhost:8666 in this case) and database.js config, then run npm run test:endpoints.

Codebase

The project makes extensive use of Koa, async/await functions, and the knex.js database abstraction library. The Hakai-API Primer docs for details about these libraries at a high level and a summary of the general logic of the application.

Postman

See the authorization docs for details about setting up Postman to make authenticated API requests.

Putting code into production

To put your development code into production, see deployment docs

Error handling

  • LOG_LEVEL - This can be set to limit the type of error messages that appear from logger statements in our code. Some levels are info, warn, error, debug. see the Winston package for more info.

  • DEBUG - This is an environment variable used in many projects and standardized with the Debug package. This is not at all related to LOG_LEVEL. We can use DEBUG to filter debug lines from certain packages ( eg DEBUG=knex:*,DEBUG=koa-router:*). To see all logging info use DEBUG=*.

Sentry integration

Sentry integration is configured via the environment variables SENTRY and NODE_ENV, set in .env file and package.json.

If SENTRY=true, errors get sent to sentry and are recorded. If NODE_ENV=production, sentry errors get sent to Sentry and an alert is sent. If NODE_ENV=production it doesnt matter what you set for SENTRY.

References