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.

Node.js apps and your account's process limit

Your cPanel hosting account has a limit on the number of processes it can run at once, and every thread counts towards it. A single running Node.js app uses several of those slots, often 10 or more. Your PHP and WordPress websites and cPanel itself need slots from the same limit.

If old copies of a Node.js app keep running (for example after the app has been changed or redeployed), they can use up the limit. When that happens:

  • all websites on the account, including PHP and WordPress sites, can return a 503 error, and
  • cPanel tools can fail with an error like cagefs_enter: Unable to fork... The user has reached resource limits.

Keeping Node.js apps under control

  • Stop apps you aren't using. In cPanel > Setup Node.js App, stop any application you don't need running (use the stop icon in the application list, or Stop App when editing it). You can start it again later.
  • Restart rather than duplicate. After changing an app, use Restart on the existing application instead of creating a new one for the same code.
  • Watch your usage. Check the process and entry process figures in cPanel's Statistics panel and Resource Usage. See How to Diagnose What is Causing Resource Spikes on Your cPanel Hosting Plan and Managing Plan Resources.
  • Running several Node.js apps? Consider giving them their own hosting plan or a VPS, so they can't take your other websites offline.

If your sites are already returning 503 and cPanel won't open because the account has reached its limit, open a helpdesk ticket so our team can clear the stuck processes.

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}`);
    });
    

 


Was this answer helpful?

Still need help?

Our friendly support team are ready to offer assistance with any issues you may be encountering.
Click the button below to open a ticket:
Open Ticket

 WordPress Hosting

Fast hosting for WordPress
Experience the best in Australian WordPress hosting with lightning fast servers, built-in caching, and performance tools.

 Build Your Website

Sitejet Hosting
Build your site fast with a drag and drop editor with no coding required. 140+ quality, templates to get you started.

 Register Domains

It all starts with your domain name
Find the perfect domain and register now with our competitive pricing on all extensions.

 Web Hosting

Fast, local, secure hosting
Full featured hosting on cPanel with multiple server locations around the country.
« Back