How to Deploy a Node.js Application on cPanel

cPanel makes it easy to host, run, and manage Node.js applications directly from a visual interface using the Setup Node.js App tool (powered by CloudLinux LVE and LiteSpeed passenger).

This step-by-step guide walks you through setting up your environment, uploading application files, installing packages, and managing environment variables.

Step 1: Create the Node.js Application in cPanel

1. Log in to your cPanel dashboard.

2. Scroll down to the Software section and click Setup Node.js App.

3. Click the Create Application button.

4. Fill in the application fields:

   • Node.js Version: Select your preferred runtime version from the drop-down menu (e.g., 18.x or 20.x).

   • Application Mode: Select Development or Production.

   • Application Root: Enter the folder path where your project files will live (e.g., nodejs-app or apps/my-app).

   • Application URL: Choose the domain or subdomain and path that will serve your application.

   • Application Startup File: Name your main entry point file (e.g., app.js, server.js, or index.js).

5. Click Create in the top-right corner. cPanel will set up the virtual environment and display a virtual environment command at the top of the page.

Step 2: Upload Your Application Code

You can upload your files using cPanel File Manager, FTP, or via Terminal.

1. Go back to the cPanel main dashboard and open File Manager under the Files section.

2. Open the directory path you specified in Application Root (e.g., public_html or nodejs-app).

3. Upload your application files (package.json, main startup file, utility modules, etc.).

   • Important: Do not upload the node_modules folder. You will install dependencies directly on the server in the next step.

Step 3: Install Dependencies (package.json)

1. Navigate back to cPanel > Setup Node.js App.

2. Locate your application and click the Edit (pencil) icon.

3. If cPanel detects your uploaded package.json file, you will see a Run NPM Install button appear under the Detected configuration files section.

4. Click Run NPM Install to install all required modules.

Installing via Terminal (Alternative Method)

If you prefer using the command line:

1. Copy the virtual environment command shown at the top of your app settings page (it will look similar to: source /home/username/nodevenv/nodejs-app/18/bin/activate && cd /home/username/nodejs-app).

2. Open Terminal under the Advanced or Security section in cPanel.

3. Paste and run the copied command to enter your isolated Node.js environment.

4. Run npm install directly inside the terminal.

Step 4: Configure Environment Variables

AI applications, API integrations, and database connectors require secret keys that should never be hardcoded into source code.

1. Inside Setup Node.js App, scroll down to the Environment Variables section.

2. Click Add Variable.

3. Enter the Name (e.g., OPENAI_API_KEY, PORT, DATABASE_URL) and the corresponding Value.

4. Click Done and repeat for all required variables.

5. Click Save at the top of the page to apply the updates.

Step 5: Start or Restart the Application

1. Once dependencies are installed and environment variables are set, click Restart Application at the top of the Setup Node.js App page.

2. Visit your configured Application URL in your browser to verify that the application is running correctly.

Troubleshooting & Common Fixes

• Application Errors / 500 Internal Server Error: Check the passenger log files generated in your app root directory or check your cPanel error logs to inspect runtime output.

• Module Not Found: Ensure you ran npm install inside the correct application root path or activated the virtual environment before installing packages.

• Port Conflicts: Do not manually hardcode a fixed port like 3000 or 8080 in your listen() method. Passenger dynamically assigns a socket or port for reverse proxying. Use process.env.PORT in your startup code:

  const PORT = process.env.PORT || 3000;
  app.listen(PORT, () => {
      console.log(`Server running on port ${PORT}`);
  });