Basic Nestjs Application/API Boilerplate project with Git CI

This project is based on the Basic Docker Project with Git CI project and include:

1. Node.js + Nestjs framework + Typescript + Swagger + JSON Logging (Shellscript + Winston)
2. This project is based on the new project generated by nest new <project> command (as of 2023-03-24)
3. Two dockerfile for production and development (which will be supported by .gitlab-ci.yml)
4. Dockerfile using multiple-stage builds
5. docker-compose setup for local development
6. Minimal API implementation (version, healthcheck)

Local development using docker-compose and attach with VSCode

Preparation

Assume you are using Linux (Mac or WSL2) and your login user id is 1000

1. Clone the project
2. Prepare the .env (for docker-compose) and .env-app (for Node.js app) files
3. Refer to sample.env-* for the details
4. Create data folder (for vscode-server which will be running inside the container for VSCode) mkdir -p ./data/vscode-server
5. The VSCode extension and some required data will be saved in this persistence folder.
6. If you have started the service before making the directory (under your user account), you may get error when you attach VSCode. To resolve it, change the data and vscode-server folder ownership to you.
7. Build the image docker-compose build

Start the environment as a dummy-daemon service

Assume you have installed docker extension in VSCode

docker-compose up -d

Attach container with VSCode

1. Start the service (if not yet)
2. Start VSCode and locate Docker in the left tab panel, click the docker icon
3. Locate the running container of your application (e.g. basic-nestjs-app)
4. Right-click the container instance, select Attach Visual Studio Code
5. From the dropdown menu, select the instance again
6. A new VSCode Window will be shown if success
7. If it is the first time, please pick the working folder to /home/node/app

Run the server application

1. In the VSCode terminal (within the container), type yarn start or yarn start:dev
2. To use the VSCode debugger, click the debug and launch the Debug Nest Framework (See launch.json) for details

Swagger

The Nest Swagger framework is added into this project. For details, please see Nestjs OpenAPI documentation.

When the is started and either NODE_ENV is not set to production OR ENABLE_SWAGGER is true, the swagger will be enabled. It can be access via URL: /api. For example: http://localhost:3000/api

About the Winston Logger and Price Service Core

To use the Node.js Logger with Winston and output as a json format (required by Price's K8s best practice), please consider to use Price Service Core's Utility Service for logger.

The Price Service Core has benn installed in this project. This is the command used: yarn add --registry https://repo-manager.price-hk.com/repository/npm-group/ @price/service-core@0.4.0

And a wrapper class WinstonLoggerService (file src/logger/winston.service.ts) is created as well. Logger configration has also implemented in this project too.

To use this, in your TS source code:

1. import the class. e.g.: import { WinstonLoggerService } from './logger/winston.service';
2. Set the context in constructor:

   constructor(private logger: WinstonLoggerService) {
     this.logger.setContext(this.constructor.name);
   }
   

3. Log as needed: this.logger.debug("the message to log");

---

Working with the sample user-API (CURD)

API-Doc: /api

• Example: http://localhost:3000/api

Note:

1. The following use Linux cURL command to operate the API.
2. Header is provided. Especially for POST and PATCH

Create User

curl -X POST -H 'Content-Type: application/json' -d '{ "name": "Tester 1" }' 'http://localhost:3000/users'

List Users

List users (with header outpu):

curl -i 'http://localhost:3000/users'

Formatted result with JQ:

curl -s 'http://localhost:3000/users' | jq

Get specific user

curl -s 'http://localhost:3000/users/0' | jq

Update specific user

curl -X PATCH -H 'Content-Type: application/json' -d '{ "name": "Tester 2" }' 'http://localhost:3000/users/1'

Note: Header must be provided.

Delete specific user

curl -X DELETE 'http://localhost:3000/users/1'