מאגר מידע

You can run a Node.js application directly on your cPanel hosting account — an Express API, a Next.js site, a webhook receiver, a small dashboard — without a VPS. Because every account here runs under CloudLinux, cPanel includes the Setup Node.js App tool (the CloudLinux Node.js Selector). It builds an isolated virtual environment for your app, lets you pick the Node version, installs your dependencies, and serves the app through Phusion Passenger so you never have to manage a long-running node process yourself. This article walks through the whole process and the gotchas that trip people up.

What you’ll need

• A cPanel plan with Setup Node.js App available. If you don’t see it under Software, open a ticket and we’ll confirm it’s enabled for your plan.
• Your application code, with a startup file (commonly app.js) and a package.json listing your dependencies.
• Optional but handy: SSH or cPanel Terminal access for running npm commands by hand.

Your app does not need to be uploaded before you start — you can create the application first, then upload code into its folder with File Manager, FTP/SFTP, or git.

Where to find it

1. Log in to cPanel.
2. Under Software, click Setup Node.js App.
3. Click Create Application.

Creating the application

You’ll fill in a short form. Each field matters:

Click Create. cPanel provisions the virtual environment and writes the Passenger configuration into an .htaccess file in your application root automatically. Don’t delete those directives — they’re what route web traffic to your app.

Write your app to use Passenger’s port

This is the single most common mistake. Under Passenger you must not hard-code a port like 3000. Listen on the port Passenger hands you via process.env.PORT:

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

const port = process.env.PORT || 3000;

http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello from ipxcore Node.js hosting\n');
}).listen(port);

An Express app is the same idea — app.listen(process.env.PORT || 3000). Locally the fallback port is used; on our servers Passenger sets PORT for you.

Installing dependencies

Make sure your package.json is in the application root, then either:

• The easy way: on the Setup Node.js App screen for your app, click Run NPM Install. cPanel reads package.json and installs everything into the app’s virtual environment.
• By hand: the app’s page shows an “Enter to the virtual environment” command. Copy it and run it over SSH/Terminal so npm runs against the right Node version. It looks like this:

source /home/USERNAME/nodevenv/nodejsapp/20/bin/activate && cd /home/USERNAME/nodejsapp

Once the virtual environment is active your prompt changes, and node/npm point at the selected version. Now you can run the usual commands:

npm install
npm install express      # add a single package
npm run build            # run a script from package.json

Always install through this virtual environment — running a plain npm install outside it uses the wrong Node and is the usual cause of “module not found” errors at runtime.

Environment variables

On the app’s page there’s an Environment variables section. Add key/value pairs (database URLs, API keys, NODE_ENV, etc.) there rather than committing them to code. Read them in your app via process.env.MY_VARIABLE. After adding or changing a variable, restart the app for it to take effect.

Starting, stopping, and restarting

The app’s page has Start App, Stop App, and Restart controls. You need to restart after you:

• deploy new code,
• run NPM Install or change dependencies,
• add or edit an environment variable.

If you prefer the command line, you can trigger a restart without the UI by touching a restart.txt file in the app’s tmp directory — Passenger reloads on the next request:

mkdir -p ~/nodejsapp/tmp && touch ~/nodejsapp/tmp/restart.txt

How requests reach your app

Passenger sits in front of your application. A request to your Application URL hits Apache/NGINX, Passenger spins your app up on demand (and keeps it warm), and proxies the request to it. You don’t open ports, and you don’t run node app.js as a background process — Passenger owns the process lifecycle. Static assets can still be served straight from disk; only dynamic routes go to Node.

What shared hosting can and can’t do

The Node.js Selector is great for web apps and APIs that respond to requests. A few limits to keep in mind on shared hosting:

• No manual daemons. Don’t run pm2, forever, or a bare node process in the background — CloudLinux LVE limits will reap it. Let Passenger manage the app.
• Always-on background workers (queue consumers, WebSocket servers that must never sleep, long-lived cron-style loops) aren’t a good fit, because Passenger idles the app out when there’s no traffic. For those, a VPS or dedicated server is the right tool.
• Resource caps apply. CPU, memory, and process counts are bounded by your plan’s LVE limits, exactly like PHP.

Troubleshooting

• 503 / “Incompatible Application” / blank page: the app failed to boot. Check the Passenger log (set a log path when creating the app), confirm the startup file name matches, and verify the app starts cleanly when you run it inside the virtual environment.
• “Cannot find module …”: dependencies weren’t installed into the venv. Run Run NPM Install, or npm install after entering the virtual environment — then restart.
• Changes don’t show up: you didn’t restart. Hit Restart or touch tmp/restart.txt.
• Port / EADDRINUSE errors: you hard-coded a port. Use process.env.PORT.
• Wrong Node version behavior: change the version in the UI, then re-run NPM Install so native modules rebuild against the new version.

Still stuck? Open a ticket with your Application URL and a copy of the Passenger log and we’ll take a look. (Note that we can help with the hosting environment — we can’t debug your application code for you.)