The Dojo

Setup your development environment

A tutorial describing how to setup your development environment for the DojoAPI.

Introduction

This tutorial describes how to setup your development environment for building the Dojo API by detailing the prerequisites and dependencies needed.

Technologies

The API is built using NodeJS and NPM.

The programming language used is Typescript v5.

Prerequisites

In order to build the API you will need the following tools:

  • NodeJS (version 20 or higher)
  • NPM (version 10 or higher)

Install NodeJS and NPM by following the instructions on the official website. Or via Node Version Manager (NVM) by following the instructions on the official website.

Dependencies

Here are the main dependencies used by the API (you do not need to install them manually or globally on your system):

  • Axios: a promise-based HTTP client for the browser and Node.js. It is used to make HTTP(S) requests to the Dojo backend and Gitlab.
  • Dotenv: used to load environment variables from a .env file.
  • Dotenv-vault: a CLI to sync .env files across machines, environments, and team members.
  • Express: a minimal and flexible Node.js web application framework that provides a robust set of features for web and mobile applications. Used to create the API server.
  • express-validator: used to validate and sanitize express requests.
  • Morgan: used to log HTTP requests.
  • JsonWebToken: used to generate and validate JSON Web Tokens.
  • Prisma: a modern database access & ORM for Node.js. Used to construct (from scratch and migrations) and interact with the database.
  • Winston: used for logging purposes. Used in combination with Morgan to log HTTP requests in the format defined with Winston.
  • zod: a TypeScript-first schema validation with static type inference. Used in the projet to validate json files created by the user.

Installation

First of all, you need to clone the repository:

git clone --recurse-submodule https://gitedu.hesge.ch/dojo_project/projects/backend/dojobackendapi.git

Then, you need to move to the project's directory:

cd dojobackendapi/ExpressAPI

To install the dependencies listed above you can use the following command in the base directory of the project:

npm install

Environment variables

Environment variables are used to store sensitive information such as API keys, passwords, etc. They are also used to store configuration information that can be changed without modifying the code.

Using on your development machine

To use environment variables on your development machine, you need the .env.keys file in addition of the .env.vault file present in the repository.

The .env.keys file have to be requested to the project maintainer: Michaël Minelli.

Decrypting the environment variables

You can decrypt env var stored in the .env.vault file with the following commands in the project's main folder. Here is an example of how to decrypt the environment variables for the development environment:

npx dotenv-vault local keys
 environment DOTENV_KEY
 ─────────── ─────────────────────────────────────────────────────────────────────────
 development dotenv://:key_1234@dotenv.local/vault/.env.vault?environment=development

Set DOTENV_KEY on your server

npx dotenv-vault local decrypt 'dotenv://:key_1234@dotenv.local/vault/.env.vault?environment=development' > .env.development

How to modify the environment variables

You can modify environment variables in .env files that you have previously decrypted. You also need to re-encrypt the modified .env files to store them in the .env.vault with the following command:

npm run dotenv:build

Database

For the development, you can use the docker compose file in the Resources/DevInfra/ folder.

The following command have to be executed in the base directory of the repository:

docker compose -f Resources/DevInfra/docker-compose.yml up -d

This will run a MariaDB database on port 59231 with the following credentials: root:9buz7f312479g6234f1gnioubervw79b8z

A second container is created with the Adminer tool on port 62394.

Structure creation and seeding

The following command (to be executed from the ExpressAPI folder) will create the database structure and seed it with some example data.

npm run database:deploy:dev

Run the API

To run the API (in dev mode) you can use the following command in the base directory of the project:

npm run start:dev