Setup Guide

You can setup Node.js apps through cPanel by going to the "Setup Node.js App" button, clicking "Create Application" and filling out the details there, including application root, url, and startup file.

• The Application Root tells the server where your application code is stored.
• The Application Url determines what public url your application will be accessible from; more information below.
• The Application Startup File is the name of the entry point Javascript file for your application. This is the same 'main' file referenced in your package.json file if you have one.

Click the "Run NPM Install" button to install your application's dependencies. Then you can click the "Start App" button.

The Application Url

The application url that you specify during application setup does not by itself determine what urls you can access your application from. All that the application url specified during setup does is create the appropriate path in your public html directory and adds a .htaccess file at that path, which directs any http requests to that path over to your application. If your application does not have logic based on the request path, this will allow your application to be accessed at the url you specified. For example, something like the following code snippet from cPanel's Node.js setup example would work great.

const http = require('http');
const hostname = '127.0.0.1';
const port = 3000;

const server = http.createServer((req, res) => {
  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/plain');
  res.end('Hello World! NodeJS \n');
});

server.listen(port, hostname, () => {
  console.log(`Server running at http://${hostname}:${port}/`);
});

However, many (most) applications provide multiple services at different paths with some routing logic based on the request path. For these applications, Phusion Passenger does not clip the base application url from the request before passing the request to your application, nor does it pass the base application url to Node.js through an environment variable or some other means. So, if your application uses routing like in the following code snippet with express, it will not work:

const express = require('express');
const hostname = '127.0.0.1';
const port = 3000;

const app = express();

app.get('/hello', (req, res) => {
  res.send('Hello Route! Express NodeJS');
});

app.listen(port, hostname, () => {
  console.log(`Server running at http://${hostname}:${port}/`);
});

This can be fixed by adding a BASE_URL environment variable to pass in the configured application url (more on adding environment variables below) and stripping that string off the request url before the rest of your routing takes place.

const base_url = process.env.BASE_URL || '';

const app = express();
const someRoute = express.Router();
// Set up someRoute...

app.use(base_url, someRoute);

With our hello world example, that would give us...

const base_url = process.env.BASE_URL || '';
const express = require('express');
const hostname = '127.0.0.1';
const port = 3000;

const app = express();
const route = express.Route();

route.get('/hello', (req, res) => {
  res.send('Hello Route! Express NodeJS');
});

app.use(base_url, route);
app.listen(port, hostname, () => {
  console.log(`Server running at http://${hostname}:${port}${base_url}/`);
});

Environment Variables

cPanel allows you to set the environment variables under which your application will be run using the application setup interface. These environment variables can be accessed from within the Node.js code as properties of process.env. The following images show an example setup for a BASE_URL environment variable.

A special environment variable here is the NODE_ENV application mode variable. It will always be one of the lowercase strings 'development' or 'production' and it is controlled separately from other environment variables by using the "Application mode" dropdown at the top of the setup menu.

Red Herrings

Some other websites offering tips about Node.js and cPanel point to port and .htaccess configuration as possible causes of issues that you might have setting up a Node.js app, but these are red herrings.

Ordinarily, running multiple Node.js applications (or other applications) on the same port would create conflicts, leading to a need to carefully configure your application to avoid ports that are in use. However, Phusion Passenger uses reverse port binding for Node.js apps, which means that any port you specify to listen on in your application is ignored by Passenger and replaced with a random available port determined by Passenger. Then, http traffic on port 80 sent to the application url configured in application setup is redirected to your application's listener, so you don't need to worry about what ports are in use.

The .htaccess file generated by Passenger when you create your application is responsible for redirecting said http traffic to Passenger so it can reach your application. The default .htaccess file works fine; there is no need to modify it. It is possible you could have problems with your application if you have customized or removed the .htaccess file, but you can get a new one by going to cPanel's Node.js app setup and creating a new, empty application.