About this project

ims-nest-api-starter is a backend API starter template using NestJS, PostgreSQL, Redis, BullMQ and MikroORM designed for scalable applications.

Key Features

• Authentication: JWT-based token authentication for secure access.
• Authorization: Role- and permission-based access control to manage user privileges.
• Caching Support: Integrated Redis caching for enhanced performance.
• Database Management: MikroORM setup with PostgreSQL for efficient data handling.
• Queue Management: BullMQ for asynchronous tasks and event-driven architecture.
• Email Notification: Send emails using Nodemailer with BullMQ asynchronously.
• XSECURITY: An added security layer that safeguards APIs against unauthorized access, ensuring data protection and integrity.

Getting Started Guide Without Docker

1. Choose Your Local Development Tool:

   Select your preferred local development tool, such as Dbngin(comes with postgresql and redis) or any other tool that suits your needs.

   Version Requirements

   • Node.js version 18+
   • PostgreSQL 16+
   • Redis 7+

2. Configure Your Environment:

   Update your .env file with the correct database credentials and environment variables.

   Copy .env.example to .env:

   cp .env.example .env

   Configure the following variables:

   • APP_PORT
   • APP_ENV
   • JWT_SECRET
   • JWT_EXPIRATION

   For JWT Secret generation, you can use this command:

   openssl rand -base64 64

   You also need to set up your PostgreSQL user and database:

   DB_DRIVER=postgres
   DB_HOST=localhost
   DB_PORT=5432
   DB_NAME=ims-nest
   DB_USERNAME=postgres
   DB_PASSWORD=

   You can ignore this if you are using Docker (see the Docker section).

   You also need to set up your Redis server:

   REDIS_HOST=localhost
   REDIS_PORT=6379

   You can ignore this if you are using Docker (see the Docker section).

3. Install Dependencies:

   To install all necessary packages, run the following commands:

   npm install

   You can use Husky to manage git hooks:

   npx husky install

4. Migrate and Seed the Database:

   Initialize and seed the database with default data using MikroORM's migration tool:

   npm run migration:up
   npm run seeder:run

   Now, your project is ready for use. You can start exploring the API and customizing your app as needed.

5. Run the Application:

   Start the NestJS server locally:

   npm run start:dev

   The API will run on the port specified in your .env file (APP_PORT).

Getting Started Guide With Docker

1. Build the Docker Image

   To build the Docker image for the application, run the following command:

     docker-compose build

2. Start the Application

   After building the image, start the application using:

     docker-compose up

   the Api should be running at .env.docker file (APP_PORT)(8000) by default.

   You can also use docker-compose up -d to start the application in the background.

   You can also use docker-compose logs -f to follow the logs of the application.

   you can also use docker-compose up --build to build the image and start the application.

3. Run Migrations and Seed Data

   If you need to run database migrations and seed initial data, you can enter the application container with the following command:

   docker-compose exec app bash

   Once inside the container, execute the following commands:

   npm run migration:up
   npm run seeder:run

   This will apply any pending migrations and populate the database with seed data.

4. Git hook for Check You can use Husky to manage git hooks: go to root directory of your project, then run the following command:

   npx husky install

Health Check

To ensure the health of your application, we have integrated Terminus for health checks.

You can visit http://localhost:<APP_PORT>/health to verify the status.

If everything is set up correctly, you should see a response like this:

{
  "status": "ok",
  "info": {
    "ims-nest": {
      "status": "up"
    },
    "database": {
      "status": "up"
    },
    "memory_heap": {
      "status": "up"
    },
    "memory_rss": {
      "status": "up"
    },
    "redis": {
      "status": "up"
    }
  },
  "error": {},
  "details": {
    "ims-nest": {
      "status": "up"
    },
    "database": {
      "status": "up"
    },
    "memory_heap": {
      "status": "up"
    },
    "memory_rss": {
      "status": "up"
    },
    "redis": {
      "status": "up"
    }
  }
}

Testing

Run tests using Jest:

npm run test

Xsecurity Setup

IMS introduces an additional layer of security, enhancing the API's reliability and resilience. With this system, only applications possessing a shared XSECURITY_TOKEN can send API requests to the server; others will be blocked. To get started, follow the guide below.

Getting Started By default, XSecure is disabled! To enable it, set the XSECURITY_ENABLED value to true in your .env file:

XSECURITY_ENABLED=true

Other wise it will be disabled.

Installation Execute the following command to set up XSECURITY:

npm run xsecurity:install

This command generates a secret for your application and updates your .env file with the XSECURITY_SECRET field.

After running the command, you will receive output similar to this:

Generated secret: N+6WQq7RjqvE+KhMRFDtk1n09M98lBAb/P/8j/I3w/7ibNzgbJeg2a+gBjNpPbMgyXSgq0sebXzYwPwnFSmleg==
XSECURITY_SECRET key has been updated in the .env file.

Use this secret in your frontend or mobile app to generate a short-lived XSecure token, which will be verified by the backend server.

For more information on how to use XSECURITY, refer to the XSECURITY Guide.

Extra CLI Commands

Generate MikroORM Entities:

Generate entities to help improve your development flow with:

npx mikro-orm schema:generate

Run Migrations:

To manage database schema changes, use:

npm run migration:create
# or
npx mikro-orm migration:create
npm run migration:up
# or
npx mikro-orm migration:up

If you want to drop all migrations and run them again with seed data, use:

npm run migration:fresh
# or
npx mikro-orm migration:fresh --seed

Nest Cli Commands:

You can follow the Nest CLI command to create your required module, service, controller, and others. Visit: Nest CLI Overview

You can also run this command to see all the CLI commands available in your project:

nest generate --help

You can create custom CLI commands tailored to your specific needs using the nestjs-command package. This project already includes integration with nestjs-command package. For reference, check out the xsecurity command implemented in src/commands/xsecurity.command.ts.

Custom Module Creation Command

This project includes a custom command to generate a new NestJS module with a well-organized folder structure.

What this command does:

• Creates a new module using the NestJS CLI.
• Generates the associated controller and service.
• Adds additional folders (dto, repositories,) inside the module folder for organizing your code.
• Creates a types.d.ts file for type definitions.

How to Use:

1. Open your terminal and navigate to the project root.

2. Run the following command, replacing yourModuleName with the name of the module you want to create:

   npm run create:module <moduleName>

   For example, to create a module named product, you would run:

   npm run create:module product

Authors

• @AHS12

Contributors

Azizul Hakim

shovon

MD: AMAN ULLAH

License

This project is brought to you by Innovix Matrix System and is released as open-source software under the CC0 1.0 License.

Feel free to use, modify, and distribute this starter project under the CC0 1.0 license terms. Contributions are welcome to improve this template!