Enabling NodeJS in cPanel

This guide explains how to deploy and manage Node.js web applications using the Node.js Selector in cPanel. This tool is designed for running apps that need to be accessible via a web browser — for example:

• Express-powered websites or APIs
• Server-side rendered JavaScript apps (like Next.js or Nuxt)
• Headless CMS platforms like Ghost

What is the Node.js Selector?

The Node.js Selector is a tool provided in cPanel that allows you to:

• Run multiple Node.js applications side-by-side, each in its own isolated environment
• Choose the specific Node.js version required by your app (e.g. 14, 16, 18)
• Host apps on your main domain, subdomains, or within subdirectories
• Use a preconfigured web server (Phusion Passenger) that automatically serves your app over standard web ports (80 and 443)

Under the hood, the Node.js Selector uses Phusion Passenger to manage your application. Passenger handles routing and process management, meaning your app:

• Does not need to bind to a port (e.g. 3000 or 3001)
• Should not call app.listen(...)
• Must instead export the app so Passenger can handle web requests properly

This article walks you through the graphical method of creating and managing Node.js apps in cPanel and understand how to set them up to work in this environment. It also covers how to install dependencies and use SSH to enter the app's virtual environment for development tasks.

Navigation

• Creating a Node.js Application (via cPanel)
  • Step 1: Access the App Setup
  • Step 2: Configure Your App
• Uploading Files and Installing Dependencies
  • Upload Your Code
    • Example package.json
  • Install Dependencies via GUI
• Writing the Startup File (app.js or similar)
  • ✅ Correct Example (Express)
  • ❌ Incorrect (DO NOT DO THIS)
• Managing Your App
• Using SSH for Development
• Common Issues & Troubleshooting
  • 503 Service Unavailable errors
  • Custom ports are not supported
  • Remove default files if not needed
  • Viewing logs

Creating a Node.js Application (via cPanel)

Step 1: Access the App Setup

• Log in to cPanel.
• Navigate to Setup Node.js App.

Step 2: Configure Your App

Click Create Application and configure:

• Node.js Version – Pick from available versions (e.g. 14, 16, 18).
• Application Mode – Choose Production or Development.

This sets the NODE_ENV environment variable automatically:

• Production: Enables optimisations and disables debugging
• Development: Enables verbose logging, stack traces, and error details

• Application Root – The folder in which your app files reside (e.g. myapp).
• Application URL – Select domain or subdomain that will serve the app.
• Startup File – The entry point for your app (e.g. app.js, server.js).

Click Create when done.

Uploading Files and Installing Dependencies

Upload Your Code

Use File Manager or SFTP to upload your app files into the application root directory that you created earlier.

Example package.json

{
  "name": "myapp",
  "version": "1.0.0",
  "description": "Example Node app",
  "main": "app.js",
  "dependencies": {
    "express": "^4.18.2"
  }
}

Install Dependencies via GUI

• Go back to Setup Node.js App in cPanel.
• Click the pencil icon to edit the app.
• Press Run NPM Install – this will install modules listed in package.json.

Writing the Startup File (app.js or similar)

Your startup file is the main entry point for your application — it’s the file specified during app creation in the Node.js Selector. This is what Phusion Passenger uses to launch and serve your app.

Unlike traditional standalone Node.js apps (which listen on a custom port), applications deployed through the Node.js Selector must:

• Not call app.listen()
• Export the app object using module.exports = app

✅ Correct Example (Express)

This pattern ensures your app is compatible with Passenger:

// app.js
const express = require('express');
const app = express();

app.get('/', (req, res) => res.send('Hello from Express!'));

// Instead of app.listen(), export the app
module.exports = app;

By exporting the app instead of listening to a port, you’re letting Passenger take full control of starting and serving your app.

❌ Incorrect (DO NOT DO THIS)

const express = require('express');
const app = express();
app.listen(3000); // ❌ This will break under Passenger

Phusion Passenger is integrated into your hosting environment's web server. It:

• Spawns and manages your Node.js process
• Routes incoming HTTP requests to your exported app object, without needing to open custom ports which are not permissible.
• Ensures your app runs on demand and scales as needed

Calling app.listen() assumes you’re managing the HTTP server yourself, but under Passenger, that’s already handled for you.

Managing Your App

• Use the pencil icon to edit settings like Node version or root path.
• After making changes, click Save.
• Use the Restart button if you:
  • Change your startup file
  • Install new modules
  • Modify environment variables

Using SSH for Development

Using SSH you can activate your app’s virtual environment to run npm commands, use build tools, or debug interactively. To do so, you must first enter the NodeJS virtual environment using the command listed when you edit the app in the UI, which will look something like this:

source /home/username/nodevenv/node-scripts/20/bin/activate && cd /home/nodejs/node-scripts

Replace:

• username with your cPanel username
• myapp with your application root folder
• 20 with the Node.js version you selected (e.g. 18)

Inside the virtual environment, you can:

• Run npm install <module> manually
• Execute build commands or scripts
• Test application logic with node app.js (for non-web code)

To exit the environment, just type:

deactivate

Common Issues & Troubleshooting

503 Service Unavailable errors

• Your startup file may not be exporting the app correctly (module.exports = app is required).
• Your code might still be using app.listen(...), which is not allowed under Passenger.
• You may need to restart the app after making changes.

Custom ports are not supported

Do not attempt to bind to ports like 3000 or 3001. Phusion Passenger manages all routing internally via standard web ports (80/443).

Remove default files if not needed

If you're uploading a full app, it's safe to delete the auto-generated public/ folder and app.js file from the app root.

Viewing logs

• Use console.log() to output diagnostic messages.
• Logs may be located in ~/.nodeapp/ or under the ~/logs/ directory in your cPanel account.