How to deploy a Node.js application on cPanel

Procédure

What is Node.js?

Node.js is an open-source, cross-platform runtime environment that lets you create a website or application and host it on a server, using the JavaScript language. On our cPanel L, cPanel XL, cPanel 2XL, cPanel 3XL and CloudCP packages, we provide you with the Node.js application manager so you can set up a Node.js application on your cPanel web hosting package. Node.js versions 6 to 24 are available.

What is Phusion Passenger?

To provide our customers with a stable and robust environment for Node.js, we integrate your Node.js applications with the Apache web server using the Phusion Passenger tool.

We do not set up a reverse proxy, and Node.js applications cannot run standalone on their own web server. If you are used to running your Node.js server with a command such as node server, npm run start or pm2 start myapp, you will not be able to do this on our cPanel hosting packages. If you're using a framework, check that it's compatible with Phusion Passenger.

The execution of your Node.js application will be managed by Phusion Passenger, it will take care of executing your .js file with the correct version of node, and it will capture the http.Server listen() function call to configure the connection between your application and the Apache web server itself.

How do I install a Node.js application?

Connect to your cPanel management interface and click on the"Setup Node.js App" icon.

On the page that follows, click on the"Create Application" button to add a new application.

Then fill in the fields as required for your application:

• Node.js version: the version of Node.js your application requires.
• Application mode: allows you to define the execution mode of your application, either developer mode or production mode. This manipulates the NODE_ENV environment variable, allowing errors to be displayed in developer mode (which is useful for debugging purposes, but can also be problematic for a production application).
• Application root: the location of your Node.js application, relative to your FTP root. We recommend that you do not put your Node.js application in the public_html folder.
• Application URL: the root URL of your Node.js application.
• Application startup file: the name of the .js file that Passenger will send to Node.js to start your application.

Then click on the"Create" button once your application has been set up.

If your application startup file does not yet exist, the tool will immediately create this file with sample content. This example will display " It works! " on all HTTP requests associated with it.

Here are the contents of this example script :

var http = require('http'); var server = http.createServer(function(req, res) { res.writeHead(200, {'Content-Type': 'text/plain'}); var message = 'It works!\n', version = 'NodeJS ' + process.versions.node + '\n', response = [message, version].join('\n'); res.end(response); }); server.listen();

You can also edit the package.json file from the interface to add dependencies and install these dependencies using the " Run NPM Install " button:

Note that you need to restart your application if its dependencies have been modified.

You can also define environment variables in the Environment variables section if your application relies on them to obtain certain parameters.

Accessing your application from the terminal

Using the command line terminal is an integral part of the Node.js ecosystem. To access your application's environment from the terminal, connect to it (from the cPanel web terminal or from an SSH client) and copy the command shown to enter your application's environment:

This action will automatically activate the correct virtual environment for your application, including the correct version of Node.js and NPM, as well as the dependencies installed in the environment (instead of being installed in the " node_modules " folder in your applications folder).

Debugging a Node.js application

To debug a Node.js application, you can consult the Apache error log. The Apache error log file contains :

• STDOUT and STDERR output from the Node.js application
• Passenger-related errors
• Apache-related errors

If you have manually set the PassengerLogFile value in your site's .htaccess file, the STDOUT and STDERR output and Passenger-related errors are sent to this file instead of the Apache log file.

You can also set the PassengerFriendlyErrorPages value to on in your .htaccess file to display errors relating to the start-up of your Node.js application directly on the web browser.

Common Node.js errors

Process stopped when running npm install

Possible reasons: Your process may be stopped by the server if it is running beyond the execution time and/or quantity of resources (CPU, RAM, etc.) authorised for your hosting package. You can consult the process stop history using our " Logs " tool available from your cPanel interface.

Solution: You can limit the RAM memory used by npm using the NODE_OPTIONS environment variable as follows:

NODE_OPTIONS='--max-old-space-size=2048' npm install

This example shows, for example, a limit of 2048 MiB (2 GB).

Specified directory already used by /home/$USER/public_html/monapp when created from Setup Node.js App

Possible reasons:

• A Node.js, Python or Ruby application published in the specified directory already exists.
• Theroot application and the specifiedURL application point to the same folder.

Solution:

• Check that no Node.js, Python or Ruby application is published on the specified folder. You can check the .htaccess file for the folder in question from the file manager or your usual FTP client to quickly identify this.
• Make sure that your application files (.js, package.json ...) indicated by application root are not in the publication folder indicated by application URL. Unlike PHP applications, the files for a Node.js application do not need to and should not be located in public_html.