sh.notifier.queuer.backend v1.0.0-develop.3

Description

This repository is defined a basic template for the backend application that exposes a REST API layer. NOTE: Do not use this repository for creating projects that contain integration jobs

Releasing new builds

There are 2 main scripts for releasing:

• npm run release which triggers a semantic release version bump, it updates the version and updates the CHANGELOG.md, then commits, tags and push to the remote.
• npm run publish:app which publishes a github release and adds that zipped build as extra asset
  • you need github cli for this: https://github.com/cli/cli#installation

Scaffolding structure

Following explain all folder (F) and files (D) into the repository

• F .husky Here are contained all husky hooks; through them is possible to run one or more command in specific git action. In this boilerplate only the pre-commit hook is used, through which the lint and prettification tasks can be executed. For more info go here and here
• F api NAME CONVENTION: %swagger-name%.swagger.yaml or %swagger-name%.yaml ALREADY DEFINED: authentications.swagger.yaml In this folder are contained all swagger files in yaml extention; through this files is possible define a swagger layer and a validation layer for the exposed API's. For more info go here
• F configs NAME CONVENTION: %configuration-name%.config.json ALREADY DEFINED: server.config.json swagger.config.json security.config.json db.config.json In this folder we store our config files in order to use it in the application in json format. The *.sample.json files are inused files with only purpose to suggest the configuration allowed by the project, particularly useful when you not know the project. You are free to delete them, but if you don't, remember to always update them. For more info about default configuration go here
• F controllers NAME CONVENTION: %controller-name%.controller.json ALREADY DEFINED: authentications.controller.js Store here your controller. In this files you can define the DTOs and validation semantic logics for your APIs. NOTE: Remember to use call your methods exactly as you defined in the operationId property in the swagger files. For more info go here
• F enums NAME CONVENTION: %enum-name%.enum.js Store here your enumerators. In these files you basically save constants to use as enumerators so that you can reuse these within the project and not have to remember each time what a particular identifier corresponds to. By default are defined the error enumerators used by the Exception classes.
• F libs (DEPRECATION WARNING) In this folder are stored some utility files used to retrive the user informations by Service Help session. NOTE: In the next future this folder become a npm dependency
• F mappers NAME CONVENTION: %mapper-name%.mapper.js ALREADY DEFINED: common.mapper.js Store your factory mappers here, i.e. all those functions used to convert an object into another form. Is included the common.mapper that stored all commons functions; read more for this topic here (AGGIUNGERE LA WIKI).
• F middlewares NAME CONVENTION: %middleware-name%.middleware.js ALREADY DEFINED: Read more here about already defined middlewares Store here all your middlewares and interceptors functions. For more info about middlewares and interceptor pattern read here and here
• F node_modules Your dependecies are stored here. Do not touch this folder because is generated by NPM
• F queries NAME CONVENTION: %entity-name%.query.js Store here all your queries in order to use them into your repositories or services
• F repositories NAME CONVENTION: %entity-name%.repository.js Store here all your repositorites functions, in order to implement the repository pattern. A repository manage only the interfaces between BE and DB; if you don't need these patterns you can use the services. For more info about this pattern here and here
• F services NAME CONVENTION: %entity-name%.service.js Store here all your API business logics. If you have not implemented the repository pattern, in this services you will also have to implement the connection with the db here.
• F utils In this folder are implemented a lot utility functions. For more read here
• D .dockerignore Such as a .gitignore, contains all folders and files to ignore when make a Docker build
• D .editorconfig EditorConfig helps maintain consistent coding styles for multiple developers working on the same project across various editors and IDEs. For more info read here
• D .eslintrc.js In this files are defined all validation code informations For more read here
• D .gitignore.js Contains all folders and files that you not want save on GitHub
• D .lintstagedrc There are defined all detections rules for the staged files and folder that need to validate before to commit them. For more read here
• D .nvmrc Here the version of node to be used is defined.
• D .prettierignore Such as a .gitignore, contains all folders and files to ignore make a code prettification.
• D .prettierrc Here are defined all prettification rules For more info read here
• D APPLICATIVE-README.md You can use this file like a readme template for new application
• D Dockerfile This file is a build manifest for Docker image creation For more read here
• D index.js This file is the project entry point
• D jsconfig.json It's a configuration file to assist your text editor. Your text editor's Language Server Protocol (LSP) looks into this file to learn more about your project. For more read here
• D nodemon.json Define all nodemon configs For more read here
• D package-lock.json Lock the installed dependencies versions
• D package.json It's a manifest for node application. Here are defined all dependencies, all scripts e same meta information about the project

Requirements

• Github access token (read more here)
• Node.js lts/iron
• Oracle Instant Client 19.8 or higher

Installation

• Add the boilerplate remote to your project

    git remote add boilerplate https://github.vodafone.com/VFDE-VNO-Digital/sh.boilerplate.backend

• Disable all boilerplate tags (so as not to mix the project tags with boilerplate tags)

    git config remote.boilerplate.tagsOpt --no-tags

Update

In order to update the boilerplate in your project (or make the first installation) need to run the following command:

  git pull boilerplate master

NOTE: Be sure not to upgrade unless you have developments to commit

Configurations

In the configs folder, add your configuration files, which are: 1. db.config.json 2. server.config.json 3. swagger.config.json In order to compile these files, you can use as a reference the *.sample.json files contained in the same folder. Below is the list of properties that you can configure.

NOTE: Please use the .sample.json files as guideline for configurations. NOTE: This files are only a guideline but you are free to change them in your project in according to the specific implementation of your project.

Database

In the file db.config.json will be add all db connection that will be enstablish.

[
  {
    "alias": "main",                                          // Name of connection (that will be used to retrieve the options on oracle.service.js methods)
    "user": "oracle-user",
    "password": "oracle-password",
    "host": "192.168.1.1",                                    // Address of DB host
    "port": 1521,                                             // Port of DB (default 1521)
    "database": "SHDEV",                                      // Database name
    "timeoutMillis": 20000,
    "poolMap_comment": "",
    "poolMax": 3                                              // Simultaneus connections
  }
]

Server

In the server.config.json file we set all server configurations

{
  "port": 3000,                                     // Use this property in order to customize the server port (default=3000)
  "logs": {
    "level": "debug",                               // (silly, debug, info, warn, error)
    "colorize": true,
    "timestampFormat": "YYYY-MM-DD HH:mm:ss.SSSS",  // timestamp format
    "consoleEnabled": true,                         // enabling console logs
    "fileEnabled": true,                            // enabling file logs
    "dbEnabled": true,                              // enable save logs on db
    "maxFilesize": 5242880,                         // set the max size of log files (will be ignored if fileEnabled is true)
    "maxFiles": 10,                                 // set the max number of log files (will be ignored if fileEnabled is true)
    "filePrefix": "VFORCMAM",                       // prefix of log filename (will be ignored if fileEnabled is true)
    "location": "/foo/logs"                         // used to indicate where store the folder to store the logs. If the folder not exist will be created. (default=./logs)
  },
  "cors": {
    "origin": "*"                           // Indicate the origin that can communicate with these services
  },
  "certificates": {
    "keyPath": "/<path>/key.pem",                   // Define the path where to retrieve the private key of server certificate
    "certificatePath": "/<path/>server-crt.pem",    // Define the path where to retrieve the server certificate
    "caPath": "/<path>/ca-crt.pem"                  // Define the path where to retrieve the certification authority file
  }
}

N.B: If you do not set one or more of certificate properties (keyPath, certificatePath or caPath), an HTTP instance of the server will be used

Swagger

In the swagger.config.json file is possible configure the swagger and the APIs to be used

{
  "controllerPath": "./controllers",                // Path of controllers file
  "validateResponse": true,                         // If true enable backend response validation
  "enableUi": true,                                 // If true enable the swagger interface
  "apis": [
    {
      "apiPrefix": "/api/v1/",                      // Prefix of API
      "swaggerName": "operations.swagger",          // Swagger name
      "docsNamespace": "/operations/"               // Doc namespace
    }
  ]
}

Scripts

In the project directory, you can run the following scripts:

npm start

This script run an instant of your app

npm run dev

This script implements the hotreloading of your code: in other words create a new one javascript demon which in turn run the project and restart the project every time that detect a changes.

npm run dev:debug

Run the project with a demon (like npm run dev) but enable the swagger debug configuration

npm run format:check

Make a check if the prettification rules are properly applied on the codebase (do not make any changes)

npm run format:write

Make a check if the prettification rules are properly applied on the codebase and, if it can, apply automatically the prettification rules.

npm run install:husky

Execute the first installation (or reinstallation for husky) Remove the .husky/_ folder and made a clean installation.

npm run prepare

This task run detect your os and run the specific prepare subscript.

 If your OS is Windows, the prepare script detect win32 and run the subscript "prepare:win32"

npm run prepare:darwin

Specific task for MacOS Run the husky installation and update the folder permission

npm run prepare:win32

Run only the husky installation

npm run lint

Make a check if the eslint rules are properly applied on your codebase (do not make any changes)

npm run lint:fix

Make a check if the eslint rules are properly applied on your codebase and, if it can, apply automatically the fixes.

Wiki

For more informations or tutorial use the wiki page

Credits

This software uses the following open source packages:

Contributing

1. Pull the repository on your local environment
2. Implement your feature on a local feature branch
3. Push it when have been completed the developments
4. Open a PR for merge into develop branch

or

• Open an issue on Github

License

Vodafone