Last modified: 2024 June 6

Overview

This document describes how to install a Node.js web application. Node.js is a JavaScript runtime that allows you to build scalable web applications. For more information, read the Node.js documentation.

Install a Node.js application

Pre-installation settings

Before you begin, verify that your hosting provider has installed the following EasyApache 4 packages on your server:

Install the application

To install an application, perform the following steps:

1. Log in to the server via SSH as a cPanel user.

2. Create the application’s directory, relative to your home directory. To do this, run the following command:

   mkdir nodejsapp

3. Change to the application’s directory.

4. Create the app.js file with a text editor.

   Important:

   We strongly recommend that you create the file with this exact name because Passenger searches for this filename when it executes. If you create a startup file with a different name, you must specify the filename in the httpd.conf file. To do this, follow the directions in the Create a custom startup file section below.

5. Add the application’s configuration to the app.js file. This will resemble the following example:

   1 2 3 4 5 6 7 8 9 10 11 12 13

   const http = require('http') const hostname = '127.0.0.1'; const port = 3000; const server = http.createServer((req, res) => { res.statusCode = 200; res.setHeader('Content-Type', 'text/plain'); res.end('Hello World! NodeJS \n'); }); server.listen(port, hostname, () => { console.log(`Server running at http://${hostname}:${port}/`); });

Test the application

After you install the application, we recommend that you confirm it’s active. To do this, perform the following steps:

1. Log in to the server via SSH as a cPanel user.

2. Run the following command to start the application, where ** represents the version of Node.js that you want to install:

   /opt/cpanel/ea-nodejs**/bin/node app.js

   The output will resemble will the following example:

   Server running at http://127.0.0.1:3000

3. Open another terminal window and log in to the server via SSH as the same cPanel user.

4. Run the following command:

   curl http://127.0.0.1:3000

   The output will resemble the following example:

   Hello World! NodeJS

5. Stop the testing process by pressing CTRL + C keys in the open terminal window, or run the following command:

   ps aux | grep app.js

   This will return a list of pid (process ID) numbers of running programs containing the script name. Stop the test application by running the following command, where PIDNUMBER is the process ID:

   kill -9 PIDNUMBER

export PATH=/opt/cpanel/ea-nodejs##/bin/:$PATH

Register the application

After you install the application, register it. To do this, use cPanel’s Application Manager interface (cPanel » Home » Software » Application Manager).

After you register the application, you can access the application in a web browser with the following URL:

http://example.com/nodejsapp

In this example, example.com represents your website.

Restart the application

When you want your application to restart after you edit it, create the restart.txt touch file in the application’s tmp directory. This file directs mod_passenger to restart the application after you modify it. This action applies your changes to the application.

$appDir/tmp/restart.txt

Create a custom startup file

Passenger searches for the app.js filename when it executes. If you create a startup file with a different name, you must create an include file and specify the startup filename there. If you don’t do this, your application won’t function.

To specify the new filename, perform the following steps:

1. Create the /etc/apache2/conf.d/userdata/ssl/2_4/user/domain.nodejs.conf file with a text editor.

2. Add the PassengerStartupFile variable and the filename as its value in a virtual host container. This will resemble the following example:

   1 2 3 4 5 6

   DocumentRoot /user/example.com/public # Use server.js as the startup file (entry point file) for # your Node.js application, instead of the default app.js PassengerStartupFile index.js PassengerAppType node PassengerAppRoot /nodejsapp/example.com

3. Rebuild the httpd.conf file. To do this, run the following command:

   /usr/local/cpanel/scripts/rebuildhttpdconf

4. Restart Apache. To do this, run the following command:

   /usr/local/cpanel/scripts/restartsrv_httpd

Troubleshoot the application

You can find error messages in the application’s /home/user/nodejsapp/logs directory.

If you experience issues with your Node.js application, use Phusion Passenger’s™ Troubleshooting Passenger Standalone and Node.js documentation to troubleshoot the issue.

The application will not create an SSL include file

If your application will not create an SSL include file, it’s likely that you are using a Node.js application with an addon domain. This issue occurs when the Node.js application’s path differs from the addon domain’s document root path.

To fix this issue, you can create an SSL include file for the addon domain. To do this, perform the following steps:

1. Complete the steps to register the application. This action creates a configuration file that the system will store in the /etc/apache2/conf.d/userdata/std/2_4/username/example.com/ directory. In this example, example.com represents the addon domain name.

2. Copy the configuration file for your addon domain in the /etc/apache2/conf.d/userdata/std/2_4/username/example.com/ directory to the /etc/apache2/conf.d/userdata/ssl directory. To do so, use the following command:

   cp -a /etc/apache2/conf.d/userdata/std/2_4/username/example.com/application-name.conf /etc/apache2/conf.d/userdata/ssl/2_4/username/example.com/application-name.conf

3. Rebuild the Apache configuration and restart Apache with the following commands:

   1 2	/usr/local/cpanel/scripts/rebuildhttpdconf /usr/local/cpanel/scripts/restartsrv_httpd

For more information about these scripts, read The rebuildhttpdconf Script and The restartsrv Scripts documentation.

You can now access the Node.js application through the addon domain’s URL via HTTP (port 80) and HTTPS (port 443).

Application port troubleshooting

Passenger controls the port on which your Node.js application listens when it makes HTTP requests. This is known as reverse port binding. Reverse port binding allows Node.js applications to work with Passenger.

If you experience issues with the port on which your Node.js applications listen, use Phusion Passenger’s™ Reverse port binding in Node.js documentation to troubleshoot the issue.