Node.js Selector

Overview & Requirements

Installation

Command Line Interface

User Interface

Node.js Deployment

Overview & Requirements

Node.js Selector is a CloudLinux component that allows each user to easily create Node.js applications, choose Node.js version and other parameters for applications based on their needs.

Requirements

  • Node.js Selector supports Node.js versions 6.x, 8.x, 9.x and later.
  • This feature is available for CloudLinux 7, CloudLinux 6 hybridand CloudLinux 6.
  • Node.js Selector requires LVE Manager 4.0 or later.
  • It supports cPanel and DirectAdmin servers (Plesk is not supported as it already has Node.js support.) For more details, please go to Plesk & Node.js documentation here and here .
  • For more details about mod_passenger and Node.js, please read documentation here and here .
  • Node.js Selector is working with EasyApache 3 and EasyApache 4.

Installation

cPanel

To use Node.js Selector , please install Node.js packages by running the following command:

yum groupinstall alt-nodejs6 alt-nodejs8 alt-nodejs9
Also, please install LVE Manager, LVE Utils and Fusion Passenger by running the following command:
yum install lvemanager lve-utils ea-apache24-mod-alt-passenger
For EasyApache 3:
yum install lvemanager lve-utils alt-mod-passenger
And we recommend to install CageFS for better security (not mandatory) by running the following command:
yum install cagefs

Note

If during Node.js Selector usage on cPanel servers you get "ENOMEM npm ERR! errno-12" error, try to increase Memory limit in cPanel WHM → Server Configuration → Tweak Settings → System → Max cPanel process memory, then restart cPanel service with the following command to apply changes.

CloudLinux 7:

systemctl restart cpanel.service

CloudLinux 6:

service cpanel restart

DirectAdmin

To use Node.js Selector, please install Node.js packages by running the following command:

yum groupinstall alt-nodejs6 alt-nodejs8 alt-nodejs9
Also, please install LVE Manager, LVE Utils and Fusion Passenger by running the following command:
yum install lvemanager lve-utils alt-mod-passenger
And we recommend to install CageFS for better security (not mandatory) by running the following command:
yum install cagefs

Command Line Interface

Below is a list of commands hoster and end user can run in a command line.

Hoster

Get information related to Node.js: default version, list of supported versions, status of Node.js Selector , list of users, their applications, etc:

cloudlinux-selector [get] [--json] --interpreter nodejs

JSON output for get command:

{  
"selector_enabled": true | false,   
"default_version": "6.11.3",   
"result": "success",   
"timestamp": 1508667174.220027  
"cache_status": "ready"         //  or “updating” during automatic yum cache rebuild  
"available_versions": {   //  begin of  “versions”
      "6.11.3" : {   //   begin of version "6.11.3"
		"name_modifier": "",
		"status": "enabled",  //  enabled, disabled, not_installed, installing, removing
		“base_dir”: “/opt/alt/alt-nodejs6”   //  empty when version is not installed
		“users”: {   //  begin of  “users”                      
			“user1”: {   //  begin of “user1”
				“homedir”: “/home/user1”,
				“applications”: {    //  begin of “applications”
					“apps_dir/app1” : {   //   begin of application “apps_dir/app1”
						“domain”: “cltest1.com”,
						“app_uri”: “apps/my-app1”,
						“app_mode” : “development”,
						“startup_file” : “app.js”,
						“app_status” : “started”,   // ‘started’ or ‘stopped’
						“config_files” : [
							“package.json”,
							“gruntfile.js”
						],
						“env_vars” : {
							“var1” : “value1”,
							“var2” : “value2”
						},
					},   // end of application “apps_dir/app1”
					“apps_dir/app2” : {    //   begin of application “apps_dir/app2”
						<< data for application “apps_dir/app2”  (same structure as for application “apps_dir/app1” above) >>
					},   //  end of application “apps_dir/app2”
				},   //  end of “applications”
			},   //  end of “user1”
			“user2”: {   //  begin of “user2”
				<< data for user “user2”  (same structure as for “user1” above) >>
			},   //  end of “user2”
		},   // end of “users”
	},    //  end of version “6.11.3”
	"8.21.5" : {   //   begin of version "8.21.5"
		<< data for version "8.21.5"  (same structure as for version “6.11.3” above) >>
	},    //  end of version “8.21.5”
},    //  end of “versions”}   //   end of json

Set default version, supported versions, and status of Node.js Selector :

cloudlinux-selector set [--json] --interpreter nodejs (--selector-status <enabled,disabled> | --default-version <str> | --supported-versions <str>)

Note

Node.js Selector is disabled by default. If an available Node.js version is not installed Node.js Selector is always disabled and it is impossible to enable it.

To set default Node.js version, please use the following command (note that required Node.js version should be enabled):

cloudlinux-selector set --json --interpreter=nodejs --default-version=<ver>

Examples :
This command enables Node.js Selector :

cloudlinux-selector set --json --interpreter nodejs --selector-status enabled

This command sets default Node.js version as 6:

cloudlinux-selector set --json --interpreter nodejs --default-version 6

This command sets supported Node.js version as 8:

cloudlinux-selector set --json --interpreter nodejs --supported-versions='{"6": false, "8": true}'

Install required Node.js version:

cloudlinux-selector install-version --json --interpreter nodejs --version 8

Uninstall required Node.js version:

cloudlinux-selector uninstall-version --json --interpreter nodejs --version 8

Enable required Node.js version:

cloudlinux-selector enable-version --json --interpreter nodejs --version 8

Disable required Node.js version (note that it is impossible to disable default Node.js version):

cloudlinux-selector disable-version --json --interpreter nodejs --version 8

Change version for application(s):

cloudlinux-selector set [--json] --interpreter nodejs ((--user <str> |  --domain <str>) --app-root <str> | --from-version <str>) --new-version <str>

Examples :
This command changes version for the specific application:

cloudlinux-selector set --json --interpreter nodejs --user user1 --app-root apps_dir/app1 --new-version 8

Common output for all set commands:

in case of success :

{  "result": "success",   "timestamp": 1508666792.863358}

in case of error:

{  "result": "Some error message",  "details" : "Traceback: ..." ,  "context": {},  "timestamp": 1508666792.863358}

in case of warning:

{  "result": "success",  "warning" : "Some warning message" ,  "context": {},  "timestamp": 1508666792.863358}

To resolve issues related to install-version/uninstall-version commands (because they are running in the background) you may use this log file /var/log/cl-nodejs-last-yum.log It contains full yum output from the latest performed operation (install or uninstall) and it will be rewritten with each operation.

End User

WARNING

options --user and --domain are mutually exclusive now.

Get config file for the user applications

cloudlinux-selector read-config [--json] --interpreter nodejs  [(--user <str> |  --domain <str>)] --app-root <str> --config-file <name>

JSON output:

{
    "result": "success",
	"timestamp": 1508666792.863358
	"data": "content of config file as Base64 encoded string"
}

Example :

This command gets config file for user1 ’s application app1 :

cloudlinux-selector read-config --json --interpreter nodejs  --user user1 --app-root app_dir/app1 --config-file package.json
Save config file for the user applications
cloudlinux-selector save-config [--json] --interpreter nodejs  [(--user <str> | --domain <str>)] --app-root <str> --config-file <path> --content <content of config file as Base64 encoded string>

JSON output (the same as for all set commands):

{
          "result": "success",
		  "timestamp": 1508666792.863358
}

Example :
This command saves config file for user1 ’s application app1 :

cloudlinux-selector save-config --json --interpreter nodejs  --user user1 --app-root app_dir/app1 --config-file package.json  --content                                         VGh1ICAyIE5vdiAxMDo0MzoxMiBFRFQgMjAxNwo=
Get a list of applications for the specific user
cloudlinux-selector [get] [--json] --interpreter nodejs  [(--user <str> |  --domain <str>)]

Example :
This command gets a list of applications for the user1 :

cloudlinux-selector get --json --interpreter nodejs  --user user1
Create user application
cloudlinux-selector create [--json] --interpreter nodejs [(--user <str> | --domain <str>)] --app-root <str> --app-uri <str> [--version <str>] [--app-mode <str>] [--startup-file <str>] [--env-vars <json string>]

Example :
This command creates user1 's application for the domain xyz.com :

cloudlinux-selector create --json --interpreter nodejs --user user1 --app-root my_apps/app1 --app-uri apps/app1
or
cloudlinux-selector create --json --interpreter nodejs --app-root my_apps/app1 --domain xyz.com --app-uri apps/app1
Start, restart, stop, and destroy user application
cloudlinux-selector (start | restart | stop | destroy) [--json] --interpreter nodejs  [(--user <str> | --domain <str>)] --app-root <str>

Example : This command starts user1 's application:

cloudlinux-selector start --json --interpreter nodejs --user user1 --app-root my_apps/app1
Change properties for an application
cloudlinux-selector set [--json] --interpreter nodejs  [(--user <str> | --domain <str>)] --app-root <str> [--app-mode <str>] [--new-app-root <str>] [--new-domain <str>] [--new-app-uri <str>] [--new-version <str>] [--startup-file <str>] [--env-vars <json string>]

Example 1 : This command sets a production mode, new domain new.xyz.com , new Node.js version 8, new URI , new application root directory and new startup file for user1 application located on the domain xyz.com :

cloudlinux-selector set --json --interpreter nodejs  --user user1 --app-root my_apps/app1 --mode production  --new-app-root new_apps/new_app1  --new-domain new.xyz.com --new-app-uri new_apps/app1  --new-version 8  --startup-file new_app.js --env-vars '{ "var1" : "value1", "var2" : "value2" }'

Example 2 :

cloudlinux-selector set --json --interpreter nodejs  --domain xyz.com --app-root my_apps/app1 --mode production  --new-app-root new_apps/new_app1  --new-domain new.xyz.com --new-app-uri new_apps/app1  --new-version 8  --startup-file new_app.js --env-vars '{ "var1" : "value1", "var2" : "value2" }'

Note

When changing Node.js version all replies from web application to get request will be checked in Node.js Selector (before and after version changing). HTTP response codes and MIME type are comparing. So, make sure application is available via http(s) at least locally.

Run npm install command for the user application

cloudlinux-selector install-modules [--json] --interpreter nodejs  [(--user <str> |  --domain <str>)] --app-root <str>

Example : This command runs npm install for user1 application:

cloudlinux-selector install-modules --json --interpreter nodejs --user user1 --app-root my_apps/app

Note

All replies from web application to get request will be checked in Node.js Selector (before and after modules installation). HTTP response codes and MIME type are comparing. So, make sure application is available via http(s) at least locally.

Run a script from package.json file of a user application, arguments args are passed to the script

cloudlinux-selector run-script [--json] --interpreter nodejs  [(--user <str> | --domain <str>)] --app-root <str> --script-name <str> [-- <args>...]

Example :

cloudlinux-selector run-script --json --interpreter nodejs --user user1 --app-root my_apps/app --script-name test_script -- --script_opt1 --script_opt2 script_arg1 script_arg2

JSON output:

{
          "result": "success",
		  "timestamp": 1508666792.863358
		  "data": "script output as Base64 encoded string"
}

Activate virtual environment of NodeJS:

source <home_of_user>/nodevenv/<app_root>/<nodejs_version>/bin/activate

This command changes prompt to Example :

[newusr@192-168-245-108 ~]$ source /home/newusr/nodevenv/newapp4/newapp3/8/bin/activate
[newapp4/newapp3 (8)] [newusr@192-168-245-108 ~]$

After ativation user can use npm and node from a virtual environment without full paths.

User Interface

Hoster

Hoster interface allows to enable and disable Node.js, and manage individual Node.js versions.

Go to LVE Manager → Options Tab → Node.js Section . A list of installed Node.js versions is displayed. There are several columns in the list.

  • Version — displays Node.js version.
  • Path — Node.js package location.
  • Applications — number of applications that use this Node.js version. Click on a digit to go to the list of applications.
  • Enabled — displays if particular Node.js version is enabled.
  • Actions — allows to install, delete, and make default a particular Node.js version.

To display all changes immediately click Refresh link.

How to enable/disable Node.js

  • To enable Node.js move the slider to Enable .
  • To disable Node.js move the slider back to Disable .

Note

If you disable Node.js, its version for all your applications will not be changed, but you can not add a new application to this version.

Note

Node.js Selector icon in end user interface is absent when Node.js is disabled.

How to manage Node.js

The list of installed Node.js versions allows to enable and disable, install and delete, and set a particular Node.js version as a default.

Enable and disable particular Node.js version

To enable particular Node.js version do the following:

  • Move a disabled slider in the Enabled column for a particular Node.js version.
  • In the confirmation pop-up click Agree to save changes or Cancel to close pop-up.

To disable particular Node.js version do the following:

  • Move an enabled slider in the Enabled column for a particular Node.js version.
  • In the confirmation pop-up click Agree to save changes or Cancel to close pop-up.

Install and delete particular Node.js version

To install particular Node.js version do the following:

  • Click Install button in the Actions column for a particular Node.js version.
  • In the confirmation pop-up click Agree to save changes or Cancel to close pop-up.

To delete particular Node.js version do the following:

  • Click Bin icon in the Actions column for a particular Node.js version.
  • In the confirmation pop-up click Agree to start uninstall process.
  • Or just close a pop-up without any changes.

Note that it is impossible:

  • to remove default Node.js version;
  • to remove version with applications;
  • to install or remove version if another installation/uninstall process is running.

Make a particular Node.js version as a default

To make a particular Node.js version as a default do the following:

  • Click Double-Tick icon in the Actions column for a particular Node.js version.
  • In the confirmation pop-up click Agree to save changes or Cancel to close pop-up.

Note

It is impossible to make a disabled version default.

Applications column

To view and operate with the list of domains with Node.js versions click on a number in the Applications column for a particular Node.js version. A section with a list of Domains for particular Node.js version will be displayed.

Domains are displayed by three. To load more domains click on Load More button.

To change Node.js version for a particular application do the following:

  • Click Double-Arrow icon in the Actions column in a particular application row. A confirmation pop-up will be displayed.
  • In the pop-up choose Node.js version from a drop-down.
  • Click Change to confirm the action or Cancel to close the pop-up.
  • To refresh state of applications in current version you can click Refresh link.

Note

All packages of the application(s) will be re-installed.

End User

Note

Node.js Selector icon in end user interface is absent when Node.js is disabled.

End User interface allows end users to setup and manage Node.js for their web applications.
Go to cPanel → Software Section → Select Node.js Version .

Web Applications page is displayed.

There are several columns in the list.

  • App URI — application URI including the domain.
  • App Root Directory —  application root directory relative to user's home.
  • Mode — can be production or development.
  • Status — started/stopped — displays if an application is running or not and version of application.
  • Actions — allows to start, restart, stop, edit, and remove a particular application.

How to manage application

Start application

To start a stopped application do the following:

  • Click Start icon in the Actions column in a stopped application row.
  • When an action is completed a Start icon changes to Stop icon.

Stop application

To stop a started application do the following:

  • Click Stop icon in the Actions column in a started application row.
  • When an action is completed a Stop icon changes to Start icon.

Restart application

To restart started application do the following:

  • Click Restart icon in the Actions column in a started application row. A current row is blocked and when a process is completed it will be unblocked.

Remove application

To remove application do the following:

  • Click Bin icon in the Actions column in a particular application row.
  • In the confirmation pop-up click Agree to start removing or Cancel to close pop-up.
  • When an action is completed an application will be removed from the Web Applications table and a confirmation pop-up will be displayed.

Edit application

To edit application do the following:

  • Click Pencil icon in the Actions column in a particular application row. A particular application tab opens.

The following actions are available:

  • Restart application — click Restart button.
  • Stop Node.js — click Stop Node.js button.
  • Run JavaScript script — click Run JS Script button to run a command specified in the Scripts section of the package.json file. Specify the name of the script to run plus any parameters then click Ok .
  • Remove application — click Delete button and confirm the action in a pop-up.
  • Change Node.js version — choose Node.js version from a drop-down.
  • Change Application mode — choose application mode from a drop-down. Available modes are Production and Development .
  • Specify Application root — specify in a field a physical address to the application on a server that corresponds with its URI.
  • Specify Application URL — specify in a field an HTTP/HTTPS link to the application.
  • Specify Application startup file — specify as NAME.js file .
  • Run npm install command — click Run npm install button to install the package(s) described in the package.json file.
  • Add Environment variables — click Add Variable and specify a name and a value.

Application error log

Since alt-mod-passenger version 5.3.7-3 we have included support for the PassengerAppLogFile directive.

Syntax: PassengerAppLogFile path
Default: PassengerAppLogFile path-to-passenger-log-file
Context: virtual host, htaccess

By default, Passenger log messages are all written to the Passenger log file. With this option, you can have the app specific messages logged to a different file in addition. In alt-mod-passenger , you can use it in the context of a virtual host or in the htaccess file.

Debugging Errors

Since alt-mod-passenger-5.3.7-2, directives such as PassengerFriendlyErrorPages and PassengerAppEnv are available for use from htaccess file. This allows end users to see errors from their application during the development process. For example, if you add one of the following lines to the htaccess file on the application page, you will see the information (if there was an error) similar to one on the picture.

PassengerAppEnv development
or
PassengerFriendlyErrorPages on

This is a much more convenient approach to developing an application and debugging errors. On the other hand, if these directives are turned off you will see:

In this case, there is no useful information for debugging errors and this is suitable for production mode. More information about PassengerFriendlyErrorPages and PassengerAppEnv .

Node.js Deployment

The first approach - remote usage of Node.js Interpreters of different versions.
The second approach - remote usage of the cloudlinux-selector utility .

Remote Usage of Node.js Interpreters

  1. Create a Node.js project in IntelliJ IDEA/WebStorm . You can download this archive and use it as a basis.
  2. Install alt-nodejs packages on the server in use. See installation instructions .
  3. Create an application on the server. You can do it by three ways:
  • Via UI of the Node.js plugin.
  • Using the following command to create an application:
cloudlinux-selector create --interprete=nodejs --json --app-root=<USER_NAME> --app-uri=<APP_NAME> --app-mode=develompent --version=<VERSION> --domain=<DOMAIN>

Note

In the IntelliJ IDEA you can create and run any remote script (Preferences — Remote SSH External Tools — Add).

  • Choose a location of the application on the server and synchronize the files with the IntelliJ IDEA project.
  1. Set up Run/Debug Configurations in the project created.

  • Specify a path to the remote Node.js interpreter. To be able to specify the remote interpreter, you should install the Node.js Remote Interpreter plugin first. Please find more information here , using server access credentials for a user (Main menu → Run → Edit configurations...) .
  • Specify initial JavaScript file that will be run with the node command (it is the app.js file from the archive).
  • Specify Path Mappings between a local and a remote project (Preferences → Deployments → Add) . If you have created your application with the cloudlinux-selector utility or via plugin UI the Path Mappings should be as follows:
/home/<USER_NAME>/<APP_NAME>
  1. Synchronize the project directories on the local and the remote machine as per Path Mappings specified.
  2. Deploy the modules on the remote and the local machine with the npm install command (if there are dependent modules). In the UI you can click the Run NPM Install button.
  3. Run Node.js application with the configuration set at the 4th step (Main menu → Run → Run… → Select configuration) .

  1. If you are using the application from the archive attached, you can see the running application on port 3003 — http://DOMAIN:3003 .

Note

The port should be available to a server user.

The following information should be displayed on this page:

  • A version of the running Node.js interpreter;
  • Current environment variables;
  • The current time.

So that, you can be sure that deployed modules are used properly.

If you’d like to use a different version of Node.js to run an application, change a path to the interpreter in the configuration settings of the running.
To apply all changes to the project, synchronize all changes with the server and restart the running application.

  1. To debug a script, set breakpoints in the code and run the configuration via Main Menu (Main menu → Run → Debug… → Select configuration) .

Useful links:

Note

It is not required to install Passenger while working in IDE if you are using this approach.

Remote Usage of the cloudlinux-selector Utility

  1. Create an application via UI or with the command as described in the Remote Usage of Node.js Interpreters approach, step 3 (a,b) .
  2. Set up project mapping on the local machine with the created remote application /home/<USER_NAME>/<APP_NAME> (Preferences → Deployments → Add).
  3. Set up the remote commands of cloudlinux-selector (Preferences → Remote SSH External Tools → Add) for the following actions:
  • Restart application;
  • Install packages;
  • Run script;
  • Change Node.js version for the application. You can see the running app at http://DOMAIN/APPLICATION_URL To apply all changes, restart the application.