Node.js

Node.js is an execution environment for JavaScript applications running on the server.

Installation

1. Log in with superuser rights.
2. Navigate to the Software configuration section → Node.js → click the   Install software button on the toolbar.

Ispmanager will connect the Node.js repository, install the npm package manager and the latest LTS version of Node.js. To manage running Node.js applications, the control panel will install the pm2 process manager.

User settings

To give users permissions to create create sites with Node.js, go to Users → select a user → click the Edit button → in the Acces section check the Node.js box and select the Node.js default version below in the Default values section→ Save. 

Users with this feature enabled are listed with an  icon in the Status column. 

You can only disable this option if the user has no active Node.js websites.

Website configuration

To enable Node.js for a website, when creating or editing a site:

1. In the Handler field, select Node.js.
2. Specify the Node.js version. The version will be installed only for the user who owns the website. The latest version of Node.js and LTS versions starting with 12.13.0 are available.
3. Select the Connection method:
   • Socket file — Node.js application will use Unix sockets to run

   • Port — Node.js application will use the TCP port to run

     Comments

     Ispmanager will automatically select a free TCP port for Node.js. The search of a free port starts with the value specified in the NodeJsBackendBind parameter of the ispmanager configuration file. 127.0.0.1:10000 is the default value of the parameter. The directory /var/www//data/nodejs/ will be created to run Node.js through a Unix socket. To pass settings to a Node.js server file, use environment variables:

     • PORT — for a port number;
     • SOCKET — for a socket file.

     Default server file content

     const http = require('http');
     const fs = require('fs');
     
     const server = http.createServer((req, res) => {
         res.statusCode = 200;
         res.setHeader('Content-Type', 'text/html;charset=utf-8');
         const data = fs.readFileSync(process.env.INDEX_PATH, 'utf8');
         res.end(data);
     });
     
     if ("SOCKET" in process.env) {
         const socket = process.env.SOCKET;
         // Socket must be removed before starting server. This action is required. Otherwise server will not start if socket exists.
         if (fs.existsSync(socket)) {
             fs.unlinkSync(socket);
         }
         server.listen(socket, () => {
             fs.chmodSync(socket,0660);
             console.log(`Listening ${socket}`);
         });
     } else if ("PORT" in process.env) {
         const hostname = process.env.INSTANCE_HOST;
         const port = process.env.PORT;
         server.listen(port, hostname, () => {
             console.log(`Listening http://${hostname}:${port}/`);
         });
     }

Adding a Node.js project

Add your Node.js project to the created site:

1. Select Sites in the Main menu.
2. Select a required site and click the Site files button.
3. In the File manager form that opens, click Upload.
4. Select the source of the uploaded files:
   • Local computer file – click the Select file button or move the required files to the drag-and-drop zone;
   • File URL on remote server:
     • URL – a link to the file to be uploaded. For example, http://example.com/dir/file.html
     • File name – the name the file will be saved with in the current directory. If this field is left blank, the file name will be extracted from the URL
5. Make sure package.json and server.js contain the correct values relative to your project.
6. Click the Return to site list button.
7. Click the “…“ button and select Npm install. Npm install will install all the specified packages in your project. The installation process is indicated by the blinking Node.js icon in the site settings column.
8. After the installation is complete, click the “…“ button and select Restart (Node.js). The project will be restarted; the Node.js icon will turn green, indicating that it is working properly.

Configuration file

The Node.js application contains the package.json configuration file. The configuration file is used to install dependencies via npm and to control the launch of the application. For more information about the format of the configuration file, please refer to the official Node.js documentation.

Default content of package.json file

{
  "name": "doc.test",
  "version": "1.0.0",
  "description": "",
  "main": "server.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "node server.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

To edit the configuration file, go to Sites → select a site → click Configuration files. To change the path to the website application, specify the path in the main and start parameters.

To install the packages specified in the configuration file, go to Sites → select a website → menu → Npm install.

Application diagnostics

Process manager

You can check the operation of the site application through the pm2 process manager:

Allow shell access for the site owner user: Users → select a user → check the Shell box in the Access section → click Save.

Connect to the server via ssh and log in as the site owner:

su <username>

Output a list of applications:

/usr/lib/ispnodejs/bin/pm2 list

Example of response

| id  │ name            │ namespace   │ version │ mode    │ pid      │ uptime │ ↺    │ status    │ cpu      │ mem      │ user        │ watching │
├─────┼─────────────────┼─────────────┼─────────┼─────────┼──────────┼────────┼──────┼───────────┼──────────┼──────────┼─────────────┼──────────┤
│ 0   │ example.com     │ default     │ N/A     │ fork    │ 317423   │ 13m    │ 2    │ online    │ 0%       │ 60.6mb   │ <user name> │ disabled │
│ 1   │ example2.com    │ default     │ N/A     │ fork    │ 316830   │ 19m    │ 0    │ online    │ 0%       │ 61.7mb   │ <user name> │ disabled |

Request information about the desired application:

/usr/lib/ispnodejs/bin/pm2 info <name>

or

/usr/lib/ispnodejs/bin/pm2 info <id>

Example of response

Describing process with id 0 - name example.com
| status            │ online                                                    	│
│ name              │ example.com                                               	│
│ namespace         │ default                                                   	│
│ version           │ N/A                                                       	│
│ restarts          │ 2                                                         	│
│ uptime            │ 15m                                                       	│
│ script path       │ /var/www/<user name>/data/.nvm/versions/node/v18.1.0/bin/npm  │
│ script args       │ start                                                     	│
│ error log path    │ /var/www/<user name>/data/.pm2/logs/example.com-error.log     │
│ out log path      │ /var/www/<user name>/data/.pm2/logs/example.com-out.log       │
│ pid path          │ /var/www/<user name>/data/.pm2/pids/example.com-0.pid         │
│ interpreter       │ node                                                      	│
│ interpreter args  │ N/A                                                       	│
│ script id         │ 0                                                         	│
│ exec cwd          │ /var/www/<user name>/data/www/example.com                     │
│ exec mode         │ fork_mode                                                 	│
│ node.js version   │ 18.1.0                                                    	│
│ node env          │ N/A                                                       	│
│ watch & reload    │ ✘                                                         	│
│ unstable restarts │ 0                                                         	│
│ created at        │ 2022-05-11T04:25:03.051Z                                  	|

sudo -u /usr/lib/ispnodejs/bin/pm2 list

Service directories

When working with sites with Node.js, in the user's home directory are created service directories used utilities:

• /var/www/usrename/data/.npm/ — Node.js package manager data
• /var/www/usrename/data/.nvm/ — installed versions of Node.js
• /var/www/usrename/data/.pm2/ — data of the pm2 process manager

These directories are needed for Node.js to work properly. If removed, the directories will be recreated the next time the site is edited, however some information may be lost.

Site management via shell client

The site owner can execute Node.js and npm commands through a shell client. This feature is available if the Shell access option is enabled in the user settings. To open the shell client, go to Sites → select a site → menu→ Shell client. When you start the shell client, the control panel automatically:

• opens the home directory of the site
• adds the path to Node.js for the selected site to the PATH variable

To close the shell client, click .

Uninstalling Node.js

To uninstall Node.js, go to Software configuration → Node.js → Uninstall. The control panel will remove Node.js and related software — npm, pm2.

Specifics

• When you select the Node.js processing module, CMS or website builder installation is not available.
• If the content of the Node.js website has been changed, restart the website application to apply the changes: Sites → select a website → menu→ Restart.
• When restoring a Node.js site from a backup copy, ispmanager will try to use the saved port or socket settings. If a port or socket is busy, a new port or socket will be allocated for the website.