← All posts

9 min read

How to Host a Node.js App on cPanel: Step-by-Step Guide

Key takeaways

  • Host a Node.js app on cPanel using the Setup Node.js App feature: upload code, set the application root and startup file, then run npm install from the interface.
  • Point the startup file at the file that actually calls listen(), usually app.js or server.js, because a wrong startup file is the most common cause of a deployed app that never responds.
  • Click Restart in Setup Node.js App after every deploy, since Passenger keeps serving old code until you restart it.
  • A 503 error means Passenger started your app and it crashed or was never found, so run npm start manually, check the Node version, and restart.
  • Shared cPanel hosting caps CPU and entry processes and offers no push-to-deploy, so move to a VPS or PaaS once you need websockets, workers, or tested deploys.

You can host a Node.js app on cPanel using the built-in Setup Node.js App feature: upload your code, register the app with an entry file and startup command, run npm install, and Passenger serves it on your domain. This guide walks through each step, then maps the exact cPanel error messages (503, npm install failures, missing startup files) to their fixes.

What do you need before you host a Node.js app on cPanel?

Check that your host has the Node.js selector

You need a cPanel account with the Node.js selector enabled, which cPanel calls the Application Manager feature (see the cPanel Application Manager documentation). Ask your host which Node.js versions the selector offers, since old hosts sometimes pin a version your app does not support. You also want SSH or terminal access so you can run npm commands on the server.

Prepare your app locally

Your app needs a package.json at its root with a start script, because the Setup Node.js App screen asks for a startup file and cPanel runs that script to boot your app. If you already push to deploy from GitHub, the same repo works here; our walkthrough of deploying Node.js with git push covers the push-to-deploy flow.

How do you upload your Node.js app to cPanel?

You have three ways to get code onto the server: upload a zip through File Manager, use cPanel's Git Version Control, or clone over SSH. The zip route works on any host with zero setup. Git Version Control gives you git push to deploy from your existing repo. SSH is the fastest once it's enabled, but some shared hosts restrict it.

Option 1: Upload a zip through File Manager

Zip your project locally, excluding node_modules. Open File Manager, navigate to the folder your app will live in, upload the zip, and extract it. Install dependencies later through Setup Node.js App, which runs npm install on the server.

Option 2: Use cPanel's Git Version Control

In cPanel, open Git Version Control, paste your GitHub or Bitbucket clone URL, and point it at your app directory. Pull to deploy, then run npm install from the interface or terminal. This is the closest shared hosting gets to push-to-deploy. If you'd rather never touch a server at all, a managed PaaS like Omeganodes handles the deploy step for you.

How do you create the app with Setup Node.js App?

Fill in the application settings

Open Setup Node.js App from cPanel and click Create Application. Pick your Node.js version (match the one you use locally), set the application root to the folder you uploaded to, and set the application URL to the domain or subdomain you want it served from. The startup file field matters most: Passenger uses it to boot your app, so point it at app.js or server.js, whichever actually calls listen(). A wrong startup file is the most common cause of an app that deploys but never responds.

Register environment variables

Add your secrets in the Environment variables section of the same form rather than a .env file. Enter the name and value, click Add, and cPanel injects them into the process at startup. This keeps database URLs and API keys out of your repository.

Run npm install from the interface

Click Run NPM Install in the interface instead of SSH. If it fails, the error usually names a missing dev dependency or a version conflict you can fix in package.json. The long paragraph worth quoting: Passenger, the application server cPanel uses under the hood, writes startup errors to its own log rather than your browser, so a blank "Application could not be started" page tells you almost nothing on its own. The Phusion Passenger documentation explains where these error logs live and how to read them, and reading that log is the difference between a two-minute fix and an afternoon of guessing. If you would rather never read server logs again, a push-to-deploy PaaS such as Omeganodes (comparison with Heroku) handles the startup file and process management for you, though shared cPanel hosting remains the cheapest way to run a side project.

How do you point a domain and enable HTTPS?

Set the application root and domain

In Setup Node.js App, the Application root is the folder inside your home directory where your code lives, for example myapp. The Application URL field maps a domain or subdomain to that folder. Pick the domain you want to serve from, and cPanel rewrites requests so visitors hitting that domain reach your Node.js app instead of a static page. If you deploy into the wrong root, you will see your app's logs but the domain still shows the cPanel default page, so double-check this mapping before moving on.

Enable automatic HTTPS

Most cPanel hosts run AutoSSL, which issues a Let's Encrypt certificate for every domain on your account, usually within a few minutes of the domain being added. Open SSL/TLS Status in cPanel, confirm your domain shows a padlock, and force HTTPS in your app or via .htaccess if you want all traffic encrypted. If AutoSSL is failing, the certificate likely has not been issued yet or the domain's DNS does not point at the server.

If you would rather skip domain wiring and certificate management entirely, push-to-deploy with automatic HTTPS is how Omeganodes handles it: connect GitHub, deploy, and the certificate is provisioned for you.

How do you deploy updates after the first deploy?

The manual update cycle

Every update on cPanel is hands-on. Upload the changed files, open Setup Node.js App, click Run NPM Install if your dependencies changed, then hit Restart so Passenger loads the new code. Skipping the restart is the most common reason an app keeps serving the old version. If you upgraded Node, check the version pinned in your engines field against what the server runs, because a mismatch will break the restart (Node.js docs).

Why cPanel has no git push to deploy

cPanel has no native push-to-deploy. You either run git pull on the server yourself over SSH, or you keep uploading files manually, then repeat the install-and-restart steps. There is no webhook that does it for you.

If that cycle gets old, a PaaS gives you real git push deploys. Omeganodes does push-to-deploy from GitHub with automatic HTTPS, and you can pay with MTN or Airtel Money instead of a USD card (see how we handle trust and payments). Render and Railway work the same way on the deploy side, but expect card-based billing.

Why is my cPanel Node.js app returning 503 or failing to start?

Most cPanel Node.js failures come from four things: a crashed process, a version mismatch, a missing log file, or the wrong startup file. Match your error to the fix below before touching anything else.

503 Service Unavailable after deploy

A 503 means Passenger started your app and it died, or Passenger never found it. Check three things in order: run npm start from your app directory in the terminal to see the crash directly, confirm your Node.js version in Setup Node.js App matches what your code needs, and click Restart in the Setup Node.js App interface after every deploy. A restart is not optional; Passenger keeps running old code until you do one.

npm install failures and version mismatches

If npm install fails inside cPanel, the usual cause is a package needing a newer Node version than the one selected. Check the error for an engines field, then switch the Node.js version dropdown in Setup Node.js App and run install again. If install times out, delete the node_modules folder and the virtualenv from the app's home directory, then reinstall clean.

Missing or empty Passenger logs

Passenger writes to stderr.log inside the Passenger folder in your app directory, but only if your app actually writes to stderr. Add console.error output for startup failures, and check the file exists at all. An empty log usually means the app never launched, so the problem is upstream: wrong startup file or a missing dependency.

Wrong startup file errors

Passenger needs an app.js or server.js at your Application Root, or an explicit startup file set in Setup Node.js App. If your entry point is index.js or lives in src/, set the Application startup file field to match. Then restart.

Quick map:

Error messageLikely causeFix
503 Service UnavailableApp crashed or not restartedRun npm start manually, fix crash, restart in cPanel
Cannot find moduleMissing dependencyRe-run npm install in Setup Node.js App
Unsupported engineNode version mismatchChange Node version dropdown, reinstall
App loads but logs emptyWrong startup fileSet Application startup file, restart

What are the limits of hosting Node.js on shared cPanel hosting?

Shared cPanel hosting works until your app stops fitting the box. Most plans cap CPU usage and entry processes, so a traffic spike or a slow database query can trigger 503s even when your code is fine. Long-running WebSocket connections are unreliable on some setups, and Passenger may restart your app after idle periods, wiping in-memory state.

There is no build pipeline either. cPanel's Git Version Control can pull your repo, but you run npm install and restart the app manually rather than pushing to deploy.

When shared hosting stops being enough

You have outgrown it when you need websockets, background workers, or a deploy that runs tests before shipping. At that point a PaaS with push-to-deploy and automatic HTTPS is the next step.

Where else can you host a Node.js app?

cPanel vs PaaS: same criteria for every option

Run every option through the same four criteria: price transparency, push-to-deploy, automatic HTTPS, and payment methods. cPanel shared hosting wins on price and works with the mobile money billing your local host already accepts, but you manage npm installs, startup files, and Passenger logs yourself. PaaS platforms like Render, Railway, Fly.io, and Ziploy give you git push to deploy with automatic HTTPS and no YAML, so you stop thinking about infrastructure after setup.

The trade-off is cost and billing. Most PaaS providers bill in USD and expect a card that many East African developers cannot get. If your side project grows past what shared hosting handles, weigh whether the deploy convenience is worth a USD invoice.

Paying without a USD card: mobile money and regional pricing

This is where Omeganodes fits. It is a PaaS built for East African developers: deploy from GitHub to EU servers, get automatic HTTPS and custom domains, and pay with MTN Mobile Money or Airtel Money at fair regional prices. No Kubernetes, no YAML, no USD card required.

FAQ

Can I host a Node.js app on cPanel for free?

Some shared hosts bundle the Node.js selector into plans that cost a few dollars a month, but truly free cPanel hosting is rare and usually unreliable. If your budget is zero, a free tier on a PaaS often beats a free cPanel host on uptime and deploy workflow.

How do I find the Passenger error log for my Node.js app in cPanel?

Passenger writes startup errors to stderr.log inside the Passenger folder in your app directory, but the file only fills up if your app writes to stderr. Add console.error calls around startup failures, then check whether the file exists at all. An empty log usually means the app never launched, pointing to a wrong startup file or missing dependency.

Does cPanel support WebSocket apps like Socket.io?

Not reliably. Long-running WebSocket connections are unreliable on some shared setups, and Passenger may restart your app after idle periods, wiping in-memory state. For anything WebSocket-heavy, a VPS or a PaaS is a safer fit than shared cPanel hosting.

Can I pay for Node.js hosting with MTN or Airtel Money instead of a card?

Yes, some regional hosts and PaaS providers accept mobile money. Omeganodes, for example, bills in MTN Mobile Money and Airtel Money at regional prices, while most international PaaS platforms expect a USD card. Shared cPanel hosting through a local provider often works with mobile money too.

Is cPanel hosting good enough for a SaaS app with real users?

Probably not for long. Shared plans cap CPU and entry processes, so traffic spikes or slow queries trigger 503s even when your code is fine. You also get no build pipeline and no push-to-deploy. Once you need websockets, background workers, or tested deploys, move to a VPS or PaaS.

Deploy at the speed of Africa

World-class hosting, open to every developer, wherever you build and however you pay. Start free in a couple of minutes — no credit card, no lock-in.