Skip to main content
The cPanel Setup Node.js App tool registers a Node app under your account, builds an isolated node_modules directory, and hands the running process to Phusion Passenger. Each app picks its own Node version. You can run several apps under the same account on different paths or versions.

​
Available versions

Available versions vary by host. Typical rotation:
  • Node 22. Current LTS.
  • Node 20. Older LTS, still maintained.
  • Node 18. EOL upstream, kept for legacy apps.

​
Set up an app

1

Open Setup Node.js App

From cPanel home, scroll to Software and click Setup Node.js App.
Setup Node.js App tool icon
2

Click Create Application

On an empty account, you land on a list page with a + Create Application button.
3

Fill in the form

  • Node.js version: pick from the dropdown.
  • Application mode: Production or Development. Development sets NODE_ENV=development and prints fuller errors.
  • Application root: directory under your home, e.g. myapp. Created if it doesn’t exist.
  • Application URL: domain dropdown plus optional path. Use / for the root or /api for a sub-path.
  • Application startup file: defaults to app.js. Set this to whatever file exports your handler.
  • Passenger log file: optional. Useful for catching boot errors.
4

Save

Click Create. Passenger starts the app in the background.

​
Manage an app

The management page opens after creation and is reachable from the app list.
ButtonWhat it does
Run NPM InstallReads package.json and installs dependencies into the per-app node_modules.
Run JS ScriptRuns a package.json script (e.g. build, prestart) under the activated Node env.
Stop AppHalts Passenger for this app. The URL returns 503.
RestartEquivalent to touch tmp/restart.txt. Reloads the running app.
EditReopens the form. Saving overwrites the .htaccess.
DestroyRemoves Passenger registration and the per-app node_modules directory.
The Environment variables editor sits below the buttons. Names allow letters, numbers, underscores, and dashes (max 256 chars). Values are ASCII, max 1024 chars.

​
The Passenger contract

Passenger runs your code. Your code does not start an HTTP server.
app.js
const http = require('http');

module.exports = http.createServer((req, res) => {
  res.end('Hello from Passenger\n');
});
For Express:
app.js
const express = require('express');
const app = express();

app.get('/', (_req, res) => res.send('hi'));

module.exports = app;
A working example never calls app.listen(). If you copied a tutorial that does, delete that line.
Calling app.listen(PORT) from inside a Passenger-managed app produces a 503 on every request and an EADDRINUSE or Cannot find module line in the Passenger log. Remove the call.

​
Reference: where things live

WhatPath
Activated env script~/nodevenv/<app-root>/<version>/bin/activate
Installed node_modules~/<app-root>/node_modules/
Restart trigger~/<app-root>/tmp/restart.txt
Passenger config~/<app-root>/.htaccess (Selector-managed)
Boot log (if configured)path you set in Passenger log file
The activate script is what Run NPM Install sources before running npm install. From SSH: 
source ~/nodevenv/myapp/22/bin/activate && cd ~/myapp
npm install

​
Common issues

Most often: app.listen(PORT) is in the startup file. Remove it, swap to module.exports = app, then touch tmp/restart.txt to reload.
package.json is in the application root, but node_modules was built on a different machine or against a different Node version. Click Run NPM Install so it installs against the per-app env.
Default Passenger startup timeout. Add to .htaccess above the Selector-managed block:
PassengerStartTimeout 120
Common cause: the app loads a large dataset on boot, or a synchronous DNS lookup blocks startup.
Passenger forwards Upgrade: headers, but the LVE entry-process cap throttles long-lived connections. Plan around 20 to 30 simultaneous WS clients on a shared plan, or move to a Power plan.
PMEM is ~1 GB. Large dependency trees (Next.js, Strapi) can OOM during install. Run install over SSH with --prefer-offline --no-audit, or build on a dev machine and rsync node_modules and code over.

​
Recipes

Deploy Next.js

Server-rendered Next.js with a custom server.

Deploy Express

REST API behind Passenger.

​
Need a hand?

Open a ticket

Best for anything that needs an account check or a config change on our end.

Live chat

Faster for quick questions during business hours.