ISPmanager 6 Lite, Pro, Host Documentation

Node.js

ISPSystem

Note

Node.js is not supported in the current version of ISPmanager for the OpenLiteSpeed web server.

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

Installation


To install Node.js, enter Settings Software Configuration Node.jsInstall button. 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.

Note

Node.js requires Nginx web server to proxy its requests. If Nginx was not installed in the control panel, it will be installed along with Node.js. When installing Nginx, the work of the created sites may be disrupted due to the re-creation of configuration files.

User settings


To allow a user to create sites with Node.js, enter Users → select the user → Edit button → enable the Can use Node.js option and select the Node.js default versionOk. Users with this feature enabled are listed with an in the Status column. You can only disable this option if the user has no active websites with Node.js.

Website configuration


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

  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 Connection method:

    • Socket file — Node.js application will use Unix sockets to run;
    • Port — Node.js application will use the TCP port to run.

      ISPmanager will automatically select a free TCP port for Node.js. The search for a free port starts with the value specified in the NodeJsBackendBind parameter of the ISPmanager configuration file. Default value of the parameter — 127.0.0.1:10000.

      The directory /var/www/<user_name>/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 the 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}/`);
          });
      }

Example of settings

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, see 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, enter Sites → select the website → press Configuration files. To change the path to the website application, specify the path in the main and start parameters.

Note

We do not recommend changing the configuration files unless you are absolutely sure. Before saving the configuration, ISPmanager checks only the file syntax, and not the correctness of the settings.

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

Application diagnostics


Process manager

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

  1. Allow shell access for the site owner user: Users → select a user → enable the Shell access option → Save.
  2. Connect to the server via ssh and log in with the account of the site owner:

    su <username>

    <username> — the name of the user-owner of the site. For example, www-root.

  3. Output a list of applications:

    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   │ www-root │ disabled │
    │ 1   │ example2.com    │ default     │ N/A     │ fork    │ 316830   │ 19m    │ 0    │ online    │ 0%       │ 61.7mb   │ www-root │ disabled |
  4. Request information about the desired application:

    pm2 info <name>

    or

    pm2 info <id>

    <name> — site name. E.g., example.com.

    <id> - application process 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/www-root/data/.nvm/versions/node/v18.1.0/bin/npm │
    │ script args       │ start                                                     │
    │ error log path    │ /var/www/www-root/data/.pm2/logs/example.com-error.log    │
    │ out log path      │ /var/www/www-root/data/.pm2/logs/example.com-out.log      │
    │ pid path          │ /var/www/www-root/data/.pm2/pids/example.com-0.pid        │
    │ interpreter       │ node                                                      │
    │ interpreter args  │ N/A                                                       │
    │ script id         │ 0                                                         │
    │ exec cwd          │ /var/www/www-root/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                                  |

Service directories

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

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

These directories are needed for Node.js to work properly. If you remove them, the directories will be recreated the next time the site is edited, but 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, press .

Shell client interface

Uninstalling


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

Note

Unistalling is not possible if there are sites with Node.js in the control panel.

Features of work


  • 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 changed, you need to restart the website application to apply the changes: Sites → select the 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.


Thank you for your feedback!
Was the article useful?
Tell us why not:

it does not match the title

it was hard to understand

I didn't find the answer

recommendations from the article did not help

other

Tell us what you didn't like in the article: