Working on a NodeJS project

NodeJS projects are different from other types of projects in that the app itself runs a webserver. Which means it needs a port to listen on. And it also means it needs to be kept alive. If your application crashes for whatever reason, we need to ensure it restarts successfully. For that we use PM2.

PM2

You have full access to PM2 when logging into the server as your project user. You can check logs, restart your project, etc. But you do so at your own risk. Your project starts, stops and is reloaded via PM2 when managed through the platform.

For example, when you switch NodeJS versions we will execute the pm2 stop and pm2 kill commands for your project, switch NodeJS versions, and then run pm2 resurrect.

To ensure your application exits, starts and reloads gracefully, you can implement this in your code: Documentation

PM2 in turn manages your project using NPM. It uses the npm start command. It will not use npm stop to stop the process however, it simply kills it (see graceful reload documentation above).

Your project should have, in its package.json at the root of the project, a "start" key with the command to start your project.

For example:

  "scripts": {
    "start": "node docroot/server.js"
  },

This way we do not have to enforce a specific naming convention, or location, on your "main" application file.

Ports

Your NodeJS application, when running on our infrastructure, must connect to a port.

There will be an environment variable available to your application which contains the port assigned to it.

This variable is named DXP_NODE_PORT

const http = require('http');

const server = http.createServer((req, res) => {
  res.statusCode = 200;
  const msg = 'Hello World!\n'
  res.end(msg);
});

server.listen(process.env.DXP_NODE_PORT, () => {
  console.log(`Server is running`);
});

Environment variables

In case you require the port to be exposed as a different environment variable, you can set it up so your application starts using a script and in that script you export the correct environment variables.

e.g.

  "scripts": {
    "start": "./start.sh"
  },

#!/bin/bash

export MY_ENV_VARIABLE ${DXP_NODE_PORT}
node docroot/server.js

The preferred method is simply creating a .env file and placing any environment variables therein, but some frameworks read that file too late, and it can't be used for any variables that are needed during server setup. In that case, the above can offer a solution.