> ## Documentation Index
> Fetch the complete documentation index at: https://help.noxity.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Deploy a Node.js app
> Walk through deploying an existing Node.js project to cPanel: create the container, upload your code, install dependencies, set environment variables, and start the app.
Updated: May 17, 2026
By Matic Bončina
Founder
Review pending
This page walks through deploying an existing Node.js project to cPanel: from code on your laptop to a running app at a public URL. For the underlying tool reference, see [Node.js](/web-hosting/virtual-containers/nodejs).
## Before you begin
* A Node.js project on your machine with a `package.json` and an entry file (commonly `app.js` or `server.js`).
* cPanel access on a plan that exposes **Setup Node.js App**.
* A domain or subdomain already pointed at the account.
If your project uses a specific framework, the framework-specific guide is shorter:
REST API on Express.
SSR Next.js with a custom server.
## Create the container
From cPanel home, scroll to **Software** and click **Setup Node.js App**.
On an empty account you land on a list page with a single **+ Create Application** button.
* **Node.js version**: pick the highest LTS your code supports. Most projects want 22 or 20.
* **Application mode**: `Production`. Switch to Development only while chasing a boot error.
* **Application root**: a folder under your home directory, e.g. `myapp`. Created for you if it doesn't exist.
* **Application URL**: the domain dropdown plus an optional path. Use `/` for the root or `/api` to mount the app on a sub-path.
* **Application startup file**: defaults to `app.js`. Set this to the file that exports your handler.
* **Passenger log file**: optional, but worth setting (e.g. `logs/passenger.log`). It's where boot errors land.
Passenger starts an empty placeholder app. You'll get a green "running" indicator and a management page.
The full set of buttons on the management page is covered in the [Node.js reference](/web-hosting/virtual-containers/nodejs#manage-an-app).
## Upload your code
Three workflows. Pick whichever fits how your project lives today.
Zip your project locally (skip `node_modules` and `.git`), then:
1. cPanel home → **File Manager**.
2. Navigate to the application root you created (e.g. `~/myapp`).
3. **Upload** the zip, then right-click it and **Extract** in place.
4. Delete the zip once the contents are extracted.
Connect with FileZilla, Cyberduck, or VS Code's SFTP extension. Credentials are your cPanel username and password, port 22.
Sync your project into `~/myapp/`. Exclude `node_modules` and `.git` from the transfer. `node_modules` is rebuilt on the server against the per-app Node env, and `.git` adds noise without value.
For a git-tracked project, use cPanel's **Git Version Control** tool:
1. cPanel home → **Files** → **Git Version Control**.
2. **Create** → paste your repo URL, set **Repository Path** to your application root (e.g. `/home//myapp`).
3. cPanel clones the repo into that directory.
For subsequent updates, run `git pull` over SSH then hit **Restart** on the Node.js app page. See [Git Version Control](/web-hosting/cpanel/file-management/git-version-control) for the full flow.
## Install dependencies
Back on **Setup Node.js App**, find your app in the list and open it. Click **Run NPM Install**. cPanel sources the per-app virtualenv, then runs `npm install` against the `package.json` in your application root.
Big dependency trees (Next.js, Nuxt, Strapi, anything that pulls in `sharp`) can OOM during install. Run it over SSH instead, with flags that keep the resident set smaller:
```bash theme={}
source ~/nodevenv/myapp/22/bin/activate && cd ~/myapp
npm install --prefer-offline --no-audit
```
PMEM on a shared plan caps around 1 GB. If you keep hitting it, build `node_modules` on a dev machine and rsync the tree up.
## Set environment variables
The **Environment variables** editor sits below the buttons on the management page. Add entries one at a time. Variable names take letters, numbers, underscores, and dashes (max 256 characters). Values are ASCII, max 1024 characters.
Common ones to set:
| Name | Example value | Why |
| -------------- | ------------------------------------ | --------------------------------------------------------- |
| `NODE_ENV` | `production` | Many libraries flip into a faster code path on this flag. |
| `DATABASE_URL` | `mysql://user:pass@localhost/dbname` | Don't commit secrets to git. Read them from env. |
| `JWT_SECRET` | 32+ random characters | Same. Rotate from here, not from the code. |
Don't set `PORT`. Passenger ignores it. It drives the runtime over a Unix socket, not a TCP port. If your code reads `process.env.PORT`, that's fine, but the value is irrelevant.
Click **Save** under the editor, then **Restart** for the changes to take effect.
## Make the entry file Passenger-compatible
Passenger runs your code. **Your code does not start an HTTP server.** Export an `http.Server` or an Express app, do not call `.listen()`.
```js app.js theme={}
const express = require('express');
const app = express();
app.get('/', (_req, res) => res.send('Hello from Passenger'));
module.exports = app;
```
For a plain HTTP server with no framework:
```js app.js theme={}
const http = require('http');
module.exports = http.createServer((req, res) => {
res.end('Hello from Passenger\n');
});
```
Calling `app.listen(PORT)` from a Passenger-managed app produces a 503 on every request, with an `EADDRINUSE` or boot error in the Passenger log. Tutorials written for VPS deployment have this line. Delete it.
If your project shipped with a `listen()` call, edit the file in place (File Manager → right-click → **Edit**, or via SSH) before the next restart.
## Start and verify
Click **Restart**. Equivalent to `touch ~/myapp/tmp/restart.txt` from SSH.
Open the **Application URL** in a browser. Your app should respond.
The Passenger log file you set when creating the app holds the boot trace. From SSH:
```bash theme={}
tail -n 100 ~/myapp/logs/passenger.log
```
## Common issues
Almost always `app.listen(PORT)` in the startup file. Swap to `module.exports = app`, then **Restart**.
`package.json` is in the right place, but `node_modules` was built on a different machine or Node version. Click **Run NPM Install** so it builds against the per-app env.
Passenger's default startup window. If your app loads a large dataset or runs a synchronous DNS lookup on boot, raise the cap. Edit `~/myapp/.htaccess` and add above the Selector-managed block:
```apache theme={}
PassengerStartTimeout 120
```
The application URL is set to a sub-path (`/api`) but you're hitting `/`. Either change the URL in the form, or move your routes so they match the configured path.
PMEM is \~1 GB on shared plans. Run install over SSH with `--prefer-offline --no-audit`, or build `node_modules` locally and rsync the directory up.
Saving the editor stores the value but doesn't reload the process. Hit **Restart** after every change.
## Next
Wire up an Express API.
Run SSR Next.js behind Passenger.
## Need a hand?
Best for anything that needs an account check or a config change on our end.
Faster for quick questions during business hours.
* [Node.js reference](/web-hosting/virtual-containers/nodejs)
* [Virtual Containers overview](/web-hosting/virtual-containers/overview)
* [Git Version Control](/web-hosting/cpanel/file-management/git-version-control)
* [Setup Node.js App ↗](https://docs.cpanel.net/cpanel/software/setup-nodejs-app/)
* [CloudLinux Node.js Selector ↗](https://docs.cloudlinux.com/cloudlinuxos/cloudlinux_os_components/#nodejs-selector)
* [Phusion Passenger Node.js walkthrough ↗](https://www.phusionpassenger.com/library/walkthroughs/start/nodejs.html)
* [How to deploy a Node.js app with cPanel ↗](https://www.thecpaneladmin.com/how-to-deploy-a-node-js-app-with-cpanel/)