Deploying a Pure Node.js Application on cPanel

This guide explains how to deploy and run a standard Node.js application on cPanel. Unlike frontend frameworks such as Next.js, a pure Node.js application (for example Express, Fastify, or a custom HTTP server) runs directly as a server process. cPanel supports this through Phusion Passenger, which manages the Node.js runtime and proxies traffic from Apache to your application.

---

Prerequisites

• cPanel hosting with Node.js support enabled
• Node.js v16+, 18.x, or 20.x (18+ recommended)
• A working Node.js application
• package.json with a valid start script

---

Step 1: Prepare Your Node.js Application

Your project must include an entry file (commonly app.js, index.js, or server.js) that starts an HTTP server.

Example: Simple Express Server (server.js)

const express = require('express')
const app = express()

const port = process.env.PORT || 8080 // this is the recommended port

app.get('/', (req, res) => {
  res.send('Node.js app running on cPanel 🚀')
})

app.listen(port, () => {
  console.log(`Server running on port ${port}`)
})

Key Requirements

• Use process.env.PORT (Passenger injects the port)
• The server must not exit
• No localhost or hardcoded port assumptions

---

Step 2: Configure package.json

Ensure your package.json includes a proper start script:

{
  "name": "node-app",
  "version": "1.0.0",
  "main": "server.js",
  "scripts": {
    "start": "node server.js"
  },
  "dependencies": {
    "express": "^4.19.2"
  }
}

💡 cPanel uses this file to detect your application configuration.

---

Step 3: Prepare Files for Upload

Create a ZIP archive containing:

server.js
package.json
package-lock.json (recommended)

⚠️ Do not upload node_modules.
Dependencies are installed on the server.

---

Step 4: Upload the Application to cPanel

1. Open cPanel → File Manager
2. Create a folder outside public_html, for example:/apps/my-node-app
3. Upload and extract your ZIP file into this folder

---

Step 5: Register the Application in cPanel

1. Open Setup Node.js App
2. Click Create Application
3. Configure the following:

Setting	Value
Node.js version	18.x or 20.x
Application mode	Production
Application root	apps/my-node-app
Application URL	Choose your domain
Application startup file	server.js

4. Click Create

---

Step 6: Install Dependencies

After creation:

1. Scroll to Detected Configuration Files
2. Click Run NPM Install

cPanel installs all dependencies from package.json.

---

Step 7: Start or Restart the Application

Click Restart Application at the top of the Node.js App page.

If successful, your Node.js app is now live.

---

Environment Variables (Recommended)

Set environment variables directly in Setup Node.js App:

Name	Example
NODE_ENV	production
DB_HOST	localhost
API_KEY	your_key_here

Avoid using .env files unless explicitly supported by your host.

---

Common Pitfalls & Fixes

❌ App Crashes Immediately

• Ensure the server is listening on process.env.PORT
• Remove process.exit() calls

❌ 503 Service Unavailable

• Check stderr logs in cPanel
• Restart the application

❌ Modules Not Found

• Run NPM Install
• Ensure dependencies are listed under "dependencies", not "devDependencies"

---

When to Use Pure Node.js Instead of Next.js

Use a pure Node.js setup when:

• You are building an API (REST or GraphQL)
• You need background jobs or workers
• You don’t require SSR or frontend rendering
• You want minimal overhead

---

Happy deployments!