Running a Node.js app on cPanel hosting: setup, upload and npm
PrintIn short: Node.js apps are started from cPanel with the Setup Node.js App tool. You create the app, upload your project, install npm packages from the interface or the Terminal, and restart. Node.js comes with the Web Hosting SSD plans.
What to have ready
- Your project, including
package.jsonand the file that starts it (such asapp.js,server.jsorindex.js). - The domain or subdomain the app will answer on, already added in cPanel.
- The Node.js version you developed and tested with.
Step 1. Create the application
- Log in to cPanel and, under Software, open Setup Node.js App. Any existing apps are listed there.
- Click Create Application.
- Fill in the form:
| Field | What to enter |
|---|---|
| Node.js version | The version your project needs. |
| Application mode | Production for a live site, Development for testing only. |
| Application root | The folder holding the app's files, for example nodeapp. |
| Application URL | The domain, plus an optional path, where the app will be served. |
| Application startup file | The entry file, for example app.js. |
Click Create. A sample app is placed in the folder. Open the app's address in a browser; if the sample page loads, the environment is working.
Watch out: the app takes over the address you give it. Point it at the root of your main domain and the site that lived there stops showing. Use a subdomain or a separate path while you experiment.
Step 2. Upload your project
- Delete the sample files that were generated in the app folder.
- Upload your project into that folder with File Manager or FTP.
- If your entry file has a different name, click Edit on the app and correct Application startup file.
- Once a
package.jsonis present, a Run NPM Install button appears on the app page. Click it to install the dependencies. - Click Restart and load the app's address in your browser.
Common mistake: uploading the node_modules folder from your computer. On the server, packages are installed into a separate virtual environment, and node_modules in the app folder is only a link to it. A real folder with that name blocks the installation.
Step 3. Managing npm packages from the Terminal
The install button does not always succeed, especially for projects with many dependencies. In that case use the command line:
- Open Terminal in cPanel or connect over SSH. SSH access on shared hosting is enabled by our support team on request.
- At the top of the app's page in Setup Node.js App you will see a command that enters the app's virtual environment. Copy it and run it. It looks like this:
source /home/USERNAME/nodevenv/nodeapp/VERSION/bin/activate && cd /home/USERNAME/nodeapp
- Run
npm install, then restart the app in cPanel.
Handy npm commands
| Command | Purpose |
|---|---|
npm install | Installs everything listed in package.json |
npm install NAME | Adds one package |
npm uninstall NAME | Removes a package |
npm update NAME | Moves a package to a newer version allowed by package.json |
npm list --depth=0 | Lists the packages installed directly in the project |
npm outdated | Shows packages that have newer releases |
npm help | Prints help and the list of commands |
If the app will not start
- Open Edit and double-check the startup file name and the app folder.
- Read the app's error log: the form lets you set a log file where Node.js writes its error messages.
- Keep in mind that the app runs within your plan's resources (CPU, memory, processes). A process that uses too much is stopped by the account limits.
Still stuck? Include the domain and the name of the app folder when you open a ticket, so we can look at it straight away.
