Node.js REST API starter

This repository is a template to avoid rewriting all the basic authentication code for REST API's built with Express.js, MongoDB.

Table of contents

1. Why this template
2. Project architecture & Directories Structure
3. Tech stack
4. Install and configure Node.js
5. Mongodb Installation and Configuration
6. Setup and Run the Project
7. Setup GitHub actions
8. Authors
9. Contributing

Why this template

• This repository includes setup of all basic things required to start a MEAN/MERN stack backend
• Environments setup
• Connection to database(MongoDB)
• Admin routes for handling users
• Authentication - fully handled
• Social auth includes Facebook and Google OAuth2 authorization
• Provides clean structured code
• Mocha Tests to ensure API is working
• Email templates for account verification and password reset
• Token based email verification and OTP based password reset
• Body field validators

Project architecture & Directories Structure

.
├── api
│   └── v1
│       ├── controllers
│       │   ├── auth.js
│       │   └── token.js
│       ├── middlewares
│       │   └── auth.js
│       ├── models
│       │   ├── auth.js
│       │   └── token.js
│       ├── routes
│       │   ├── admin
│       │   │   └── auth.js
│       │   └── auth.js
│       └── utils
│           ├── constants.js
│           ├── response.js
│           ├── send_email.js
│           ├── templates
│           │   └── verify_email.pug
│           └── validators.js
├── ASSET_LICENSES
├── core
│   ├── config.js
│   ├── db.js
│   ├── jwt.js
│   ├── print_env.js
│   └── server.js
├── index.js
├── keys
│   ├── private.pem
│   ├── private.pem.example
│   ├── privater.pem
│   ├── privater.pem.example
│   ├── public.pem
│   ├── public.pem.example
│   ├── publicr.pem
│   └── publicr.pem.example
├── LICENSE
├── node-rest-api-auth.postman_collection.json
├── package.json
├── package-lock.json
├── public
│   └── images
├── README.md
└── tests
    └── v1
        ├── auth.js
        └── test.js

Tech stack

Node.js, MongoDB

Dependencies

1. @hapi/joi: ^17.1.1
2. @sendgrid/mail: ^7.2.3
3. axios: ^0.19.2
4. bcryptjs: ^2.4.3
5. body-parser: ^1.19.0
6. cors: ^2.8.5
7. csurf: ^1.11.0
8. dotenv: ^8.2.0
9. express: ^4.17.1
10. express-brute: ^1.0.1
11. express-brute-memcached: 0.0.1
12. helmet: ^4.0.0
13. jsonwebtoken: ^8.5.1
14. mongoose: ^5.9.27
15. multer: ^1.4.2
16. nodemailer: ^6.4.11
17. otp-generator: ^1.1.0
18. pug: ^3.0.0
19. socket.io: ^2.3.0

Dev dependencies

1. chai: ^4.2.0
2. chai-http: ^4.3.0
3. eslint: ^7.6.0
4. eslint-config-prettier: ^6.11.0
5. mocha: ^8.1.1
6. nodemon: ^2.0.4
7. prettier: ^2.0.5

Tests

Tests are written using Mocha and Chai

CI/CD

Not implemented yet

Project setup

Installation of Node.js

First thing we need to do is to install nodejs, you can find the installation steps and archives from the official website here. It is recommended to use the LTS version of node to avoid any kind of interruptions.

Install specific version using CURL

1. Install curl

sudo apt update
sudo apt upgrade
sudo apt install curl

2. Get nodejs PPA Switch to root directory

cd ~

curl -sL https://deb.nodesource.com/setup_12.x -o nodesource_setup.sh

3. Run the script under sudo:

sudo bash nodesource_setup.sh

4. Install nodejs

sudo apt install nodejs

5. In order for some npm packages to work (those that require compiling code from source, for example), you will need to install the build-essential package:

sudo apt install build-essential

Mongodb installation and configuration

In case you face any issues, refer official docs

Installing mongodb v4.2

a. Import the public key used by the package management system.

wget -qO - https://www.mongodb.org/static/pgp/server-4.2.asc | sudo apt-key add -

b. Create a list file for MongoDB

echo  "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu bionic/mongodb-org/4.2 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.2.list

c. Reload local package database.

sudo apt-get update

d. Install the MongoDB packages

sudo apt-get install -y mongod

e. Optional. Although you can specify any available version of MongoDB

echo  "mongodb-org hold" | sudo dpkg --set-selections
echo  "mongodb-org-server hold" | sudo dpkg --set-selections
echo  "mongodb-org-shell hold" | sudo dpkg --set-selections
echo  "mongodb-org-mongos hold" | sudo dpkg --set-selections
echo  "mongodb-org-tools hold" | sudo dpkg --set-selections

Configure mongodb

a. Create a directory to store data

sudo mkdir /data
sudo mkdir /data/db

b. Grant required permissions

sudo chown -R `id -un` /data/db

Start mongodb services

# start mongodb service
sudo service mongod start
# Check status of the service
sudo service mongod status

Initialize MongoDB

sudo mongod

The above command will start a MongoDB instance running on your local machine. I will pick a port to run the database, possibly it will be 27017, so your db will be hosted at

mongodb://localhost:27017/

MongoDB shell

Here you can execute your db queries. Initialize the shell by following command

mongo

Setup and run the project

1. Install the required dependencies by the following command

npm install

2. Setup public & private keys for Access and Refresh tokens Open your terminal and type the below commands to create secure private key and extracting public key from the private key. We're using a 512 bit long key, as the length increases the size of jwt also increases.

Creating private key for access token

openssl genrsa -out private.pem 512

Expected output:

Generating RSA private key, 512 bit long modulus (2 primes)
....................................................+++++
.+++++

Extracting public key for access token

openssl rsa -in private.pem -outform PEM -pubout -out public.pem

Expected output:

writing RSA key

Creating private key for refresh token

openssl genrsa -out privater.pem 512

Expected output:

Generating RSA private key, 512 bit long modulus (2 primes)
....................................................+++++
.+++++

Extracting public key for refresh token

openssl rsa -in privater.pem -outform PEM -pubout -out publicr.pem

Expected output:

writing RSA key

and place these 4 files inside keys directory in root of the project For more info on openssl, click here

3. Setup environment variables Rename the .env.example as .env and fill up your details there.

SendGrid Create an account at SendGrid SendGrid. Create a new API Key here Verify a sender email and use that email in the .env file, to verify click here

4. Place your application's Database credentials and config inside the .env.

Refer below config as example:

const dev = {
  name: "dev",
  app: {
    port: process.env.PORT || 9000,
  },
  db: {
    name: `${process.env.DB_NAME}-dev`,
    host: process.env.DB_HOST,
    port: process.env.DB_PORT,
    username: process.env.DB_USERNAME,
    password: process.env.DB_PASSWORD,
  },
};

5. Install Prettier and ESLint in VS Code

6. Google and Facebook client details, check out this article for generating client details

7. Run the project with nodemon

npm run dev

or Run as normal project

npm start

7. Run tests

npm test

Setup GitHub actions

Mock environment values

# allowed-values: prod, dev, test
NODE_ENV=dev
PORT=5000

# mongodb
# Ex: remote mongodb host: my-app.xxxxx.mongodb.net
DB_NAME=node_template
DB_HOST=localhost
DB_PORT=27017
DB_USERNAME=
DB_PASSWORD=

# tokens
TOKEN_ISSUER=Node.js
TOKEN_AUDIENCE=API_USERS
TOKEN_SUBJECT=API_ACCESS
# Ex: For 1 day- 1d, for 1 second - 1s
REFRESH_TOKEN_EXPIRES=
ACCESS_TOKEN_EXPIRES=

# host
# for remote host=https://myapp.com
host=localhost:5000

# SENDGRID_API_KEY go here
SENDGRID_API_KEY=<API-KEY>
SENDGRID_EMAIL=john@doe.com
SENDGRID_USERNAME=John

# facebook client details
client_id=
client_secret=

Create such config locally in a text file or just copy the config from .env of your db, then head over to Secrets section of your repo, an ideal link would be like this https://github.com/username/node-rest-api-starter/settings/secrets when you replace username with your own github username, then create a new Secret there with key as ENV_VARS_LOCALHOST and the value as whole of your file which you have just created in the above step. When you make a pull request to the master branch this will get executed.

Authors

Contributing

Check Contributing file