How to set up a Node.js app

Before you start

1. Check your hosting supports apps. All cPanel hosting does. If you are on DirectAdmin, open a support ticket first and ask whether your server runs Node.js apps. Most DirectAdmin servers don't, and the app will show a 404 page. See Can I host a Node.js or Python app on Webway?

2. Make your app listen on the port Passenger gives it. Never hard-code a port.

   const port = process.env.PORT || 3000;
   app.listen(port);
   

3. Know your startup file. This is the file that starts your app, usually app.js, server.js or index.js. If it uses import statements (ES modules), read If your app uses ES modules below before you begin.

4. Have a package.json in your project listing your dependencies. The app manager uses it to install packages.

These steps show cPanel. On a DirectAdmin server that supports apps, the app screen is the same CloudLinux tool, listed as Node.js App under Extra Features. Only the way you reach it differs.

Step 1: Upload your code

Your code goes in its own folder outside public_html, for example /home/username/myapp. The app manager will connect your domain to it.

1. In cPanel, open File Manager (or connect with FTP).
2. In your home folder (the one containing public_html), create a new folder, for example myapp.
3. Upload your project files into it.

Don't upload your node_modules folder. On the server, node_modules is a link into the app's own environment, and uploading your own copy breaks it. Upload everything else, including package.json.

Tip: zip the project on your computer (without node_modules), upload the zip, then right-click it in File Manager and choose Extract. It is much faster than uploading thousands of files.

Step 2: Delete the placeholder page

A new hosting account has a placeholder index.html in public_html. The web server serves that file instead of your app, so your site will keep showing the placeholder until it is gone.

1. In File Manager, open public_html.
2. Delete index.html. Delete any index.php too.
3. Leave .htaccess alone. The app manager writes lines into it that route requests to your app. If you remove them, the app stops working.

If you don't see .htaccess, click Settings in File Manager and tick Show hidden files.

Step 3: Create the app

1. In cPanel, go to Software → Setup Node.js App.
2. Click Create Application.
3. Fill in the form:

Field	What to enter
Node.js version	20 or 22 for a new app, unless your code needs an older version
Application mode	Production. Use Development only while debugging, as it shows errors in the browser
Application root	The folder from Step 1, relative to your home folder, for example myapp
Application URL	The domain or subdomain the app should answer on. Choose the domain and leave the path blank to run it at the root of the site
Application startup file	Your main file, for example app.js
Passenger log file	Optional. A file where Passenger writes app output, for example /home/username/myapp/passenger.log

4. Click Create.

The app is now registered. The screen shows a command beginning source /home/username/nodevenv/myapp/20/bin/activate. This is your app's virtual environment. You will need it later for SSH work.

Step 4: Install packages

1. On the app screen, click Run NPM Install.
2. Wait for it to finish. It reads package.json and installs everything into the app's environment.

The button is greyed out if there is no package.json in the application root. If installing fails or you need to run a build step, see How to install npm packages for my Node.js app.

Step 5: Set environment variables

If your app needs settings such as a database password or API key:

1. On the app screen, under Environment variables, click Add Variable.
2. Enter the name and value.
3. Click Save.

These are stored by the app manager and passed to your app when it starts. A .env file in your folder is only read if your code loads it (for example with the dotenv package).

Set NODE_ENV to production if your framework expects it.

Step 6: Restart and test

1. Click Restart at the top of the app screen.
2. Open your domain in a browser.

The first load is slow because the app is starting. After that it should be quick.

Still seeing the placeholder page, a 404 or a 503? See My Node.js or Python app won't start or shows an error.

After every code change

Passenger keeps your app running with the old code until you tell it otherwise. After uploading changes, click Restart on the app screen. Over SSH, creating or updating the file tmp/restart.txt inside the application root also restarts it.

If your app uses ES modules

Passenger can't load an ES module as the startup file. If your main file uses import / export, or package.json has "type": "module", the app fails with ERR_REQUIRE_ESM.

Fix: add a small CommonJS wrapper and make it the startup file.

1. In your application root, create a file named app_wrapper.cjs containing:

   (() => import('./app.js'))();
   

   Replace app.js with your real main file.

2. On the app screen, click Edit, change Application startup file to app_wrapper.cjs, and save.

3. Click Restart.

Running the app on a subdomain or in a subfolder

• Subdomain (for example api.example.co.za): create the subdomain first in cPanel under Domains, then choose it as the Application URL. Delete any placeholder file from the subdomain's folder too.
• Subfolder (for example example.co.za/app): enter app in the path part of the Application URL. Test your routes afterwards; some frameworks need a base path setting to match.

Working over SSH

For build steps, debugging, or running scripts, connect over SSH and enter the app's environment with the command shown on the app screen. See How to install npm packages for my Node.js app for the steps.

Related guides

• Can I host a Node.js or Python app on Webway?
• How to install npm packages for my Node.js app
• How to restart my app and set environment variables
• My Node.js or Python app won't start or shows an error