Project setup

How the Parro Nexus repo is set up

Parro Nexus - Repo

The Parro Nexus repo (https://github.com/topicusonderwijs/parro-nexus) is a mono repo containing all services and libraries for Parro Nexus. There are three more repositories for Parro Nexus:

Apps

The apps directory contains all Parro Nexus services. Each app is a NestJS service generated with the service generator.

An app is a NodeJS app which uses the NestJS framework. The root directory of the app therefore contains the usual NodeJS files like the package.json and tsconfig.json. It also contains a Jenkinsfile so the app can be build by Jenkins, a Dockerfile so a docker container can be created and some “dot” files for configuration of npm packages.

Environment variable

Everything which is configurable in an app must be put in environment variables. This makes it easy to config an application when it is running in a docker container on k8s. To use these env vars on your local machine without setting them as actual env vars you can use the .env.* files. Default each app has 2 files .env.template and .env.test. The .env.test is used for the tests and the env.template is used as template to show which variables are available.

For local development you will need to create a file env.local.development, which is ignored by git. In this file you can setup your local values. Since some values are secrets (i.e the database user/pass) it should never end up in the git repo. The easiest way to create a env.local.development file is to copy the env.template and fill it with the appropriate values. When you add new configurable values to a service you MUST add these to the env.template file.

The values from these .env.* files are read in the configuration.ts file located in src/config, using the cross-env npm module. In the package.json you can see the lib used in the start script: "start": "cross-env NODE_ENV=development nest start --watch".

Source code

All source code for the app is located in the src directory. The src directory contains 2 typescript files and 4 subdirectories:

  • main.module.ts: this file is the entrypoint for NestJS
  • main.ts: this file is the main typescript file which bootstraps the app
  • config: for handling all the configuration of the app
  • listeners: for implementing custom shutdown listeners, to create a gracefull shutdown for the app
  • modules: this directory contains the NestJS modules (https://docs.nestjs.com/modules) which make up the actual app
  • schema: this directory contains the generated JSON schema model

The actual app code is located in the src/modules. This directory consists of multiple NestJS modules:

Normally when you create a new app or work on an existing app you only need to change the code in the src/modules/app module. This module contains all the app specific code and can have different setups based on the service needs.

All service use the NestJS framework, so when you are new to this start by reading the docs: https://docs.nestjs.com/

Code generation

To create uniform services we use a code generation tool. This tool makes is possible to generate a skeleton app or lib project. This way we can generate all the boilerplate code in a uniform way, so you can start working on the app code right away.

The generation tool is located in code-gen/schematics. The src dir contains the files which will be added when you create a new service or lib. When you change the code in the code-gen/schematics a Jenkins job will build the code and create a NPM module @parro-connect/schematics. This module is used by the script create_nestjs_service.sh in the apps directory. Since each build creates a new version you must update the version of the package.json when you want to merge changes on the main branch, otherwise the Jenkins build will fail. The easies way is to use the npm command npm run version:for-release. This will bump the version and add an entry to the CHANGELOG.md

The code-gen also contains a git submodule for the JSON schema model code-gen/parro-connect-schema. This submodule makes it possible to generate the model classes in your project. To do so run yarn build from within the code-gen/parro-connect-schema and follow the steps.

Docker

The docker directory contain docker-compose files for running all the services or the local NATS server. To start all the Parro Nexus services at once run the start-compose.sh script. This will build and run the Dockerfile-NestJsService-Local files located in all the app directories. The Dockerfile-NestJsService-Local is a special docker setup which will mount the complete src dir in the container and runs the yarn start:dev command. This makes it possible to change code in the apps and it will be auto reloaded in the container.

Docs

The docs directory contains all the markdown files which makes up this documentation you are now reading.
The docs use the Hugo (https://gohugo.io/) static site generator with the docsy (https://www.docsy.dev/) theme.
To start the docs on your local machine run the start_docs.sh script. This will start a docker container with Hugo and starts a server you can reach on http://localhost:1313/

Libs

The libs directory contain all the Parro Nexus libraries. When you need to create a reusable library (a custom NPM module) you can use the script create_lib.sh. This will use the code generation from the code-gen dir to set up a basic library skeleton project. All libraries are build using Jenkins and are published to the @parro-connect scope (https://docs.npmjs.com/cli/v8/using-npm/scope).

Scripts

The scripts directory contains bash scripts for common tasks.