Quick Guide: Setting Up Node.js in cPanel Print

Quick Guide: Setting Up Node.js in cPanel

This guide explains how to deploy a Node.js application in cPanel using the Application Manager.

1. Prepare the application files

Before creating the application in cPanel, upload your project files to a folder inside your account. For example:

my_project

Inside that folder, you should have at least:

app.js
package.json

You do not need to upload the node_modules folder. The dependencies can be installed later from cPanel using the Run NPM Install option.

Recommendation: use app.js as the main application file, as Passenger detects it by default.

2. Create the application in cPanel

Log in to cPanel and go to:

Software > Application Manager

Then click:

Register Application

Depending on your cPanel version, the button may also appear as Deploy or something similar.

3. Complete the configuration fields

Application Name

Enter a descriptive name to identify the application.

Example:

MyWebsite

Deployment Domain

Select the domain where you want to publish the application.

Example:

yourdomain.com

Base Application URL

This field defines the URL path where the application will be available.

If you want the application to load directly at:

https://yourdomain.com/

leave the field empty.

If you want the application to load at:

https://yourdomain.com/app

enter:

app

Application Path

Enter the name of the folder where you uploaded the application files.

Example:

my_project

Do not enter the full path, such as:

/home/username/my_project

cPanel normally expects the path to be relative to the account home directory.

Deployment Environment

Select the environment depending on the current stage of the application:

• Development: use this while testing the application. It may show more detailed errors.
• Production: use this when the application is ready to be publicly accessible.

4. Environment variables

If your application needs variables such as database credentials, API keys, or configuration values, you can add them from the section:

Environment Variables

Click:

+ Add Variable

Common examples:

DB_HOST
DB_USER
DB_PASSWORD
NODE_ENV

Note: to use environment variables from Application Manager, the server must have the ea-apache24-mod_env module installed.

5. Deploy the application

Once the form is complete, click:

Deploy

or:

Register

After the application is created, cPanel will detect the package.json file.

Then run:

Run NPM Install

This will automatically install the dependencies defined in the package.json file.

6. Main application file

It is recommended that the main application file is named:

app.js

If your application uses another main file, such as:

index.js
server.js

you may need to configure Passenger to use that file as the startup file.

To avoid issues, rename or adapt the application entry point to app.js whenever possible.

7. How to check error logs

If your application does not load or shows an error such as:

503 Service Unavailable

the Node.js process may have failed to start. You can review the logs using the steps below.

Check the stderr.log file

1. Open the File Manager in cPanel.
2. Go to your application folder, the same folder configured in Application Path.
3. Look for a file named stderr.log.
4. Open it with the text editor to review the latest application errors.

This file usually shows errors related to missing dependencies, syntax issues, incorrect environment variables, or startup failures.

Enable Development mode

In Application Manager, make sure the Deployment Environment is set to:

Development

This may help the browser display more detailed errors instead of a generic message.

Important: once the application is working correctly and ready for production, change the environment back to:

Production

Check Apache errors from cPanel

You can also check web server errors directly from cPanel.

1. Log in to cPanel.
2. Go to the Metrics section.
3. Click Errors.

This section shows the latest web server error messages related to your domain. These messages may include Apache errors, Passenger errors, or issues while trying to run the Node.js application.

8. Final verification

Once the application has been deployed:

1. Open the configured domain or URL.
2. Confirm that the application loads correctly.
3. If an error appears, check the stderr.log file first.
4. Then check the Errors section inside cPanel.
5. If you made changes to the code or environment variables, restart or redeploy the application from Application Manager.

Important notes

• Do not upload the node_modules folder. Use Run NPM Install from cPanel instead.
• The package.json file must be inside the folder configured as Application Path.
• It is recommended to use app.js as the main application file.
• Do not hardcode a port in the application unless it is strictly required. Passenger manages the connection between Apache and Node.js internally.
• Use Development for testing and Production for live websites.