Running an Express or Node.js app with Setup Node.js App

You can run Express and other Node.js services directly on Flashcloud shared hosting using the Setup Node.js App tool in cPanel. Flashcloud uses LiteSpeed's native Node runner (lsnode), not Phusion Passenger, to process requests and keep persistent processes alive.

To access the tool, switch to the cPanel Classic (Jupiter) theme. The tool lives under the Software section. It does not appear in the search results within the opt-in Meridian theme, so use the Classic cPanel Theme switch in your account interface before you begin.

Creating the Node.js application

Log in to cPanel via the one-click login from your Flashcloud portal. Scroll down to Software and open Setup Node.js App. Click Create Application and configure the core fields:

• Node.js version: Select either 22.23.2 (recommended) or 24.21.0.
• Application mode: Choose Development or Production. This defines your NODE_ENV environment variable automatically.
• Application root: The directory relative to your home directory where your project files live (for example, my-node-app). Do not use public_html directly if you want clean separation from web root files.
• Application URL: Pick the domain or subdomain to route traffic from. You can also supply an optional sub-path, such as domain.com/api.
• Application startup file: The entry script executed when the runner starts (for example, app.js, index.js, or server.js).

Click Create. The tool generates your application root along with standard helper directories (public/, tmp/) and a placeholder app.js file.

You might see an inline warning stating that the application is not available or reachable after creation. If your domain or subdomain DNS has recently changed and has not propagated, this banner is harmless. It clears once the domain resolves to the server.

Configuring your code and process.env.PORT

The LiteSpeed runner assigns a dynamic socket or internal port to each application. Your application must bind to process.env.PORT rather than a hardcoded port number like 3000 or 8080.

const express = require('express');
const app = express();

const port = process.env.PORT || 3000;

app.get('/', (req, res) => {
  res.send('Service is active.');
});

app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
});

If you route the app to a sub-path like example.com/api, note that lsnode passes the full request path to your router. A visitor opening example.com/api/users sends /api/users to Express, not /users. Mount your routers on the full path prefix, or use an Express router mounted at /api:

const router = express.Router();
router.get('/users', (req, res) => {
  res.json({ status: 'ok' });
});

app.use('/api', router);

Uploading code and installing npm dependencies

Upload your application files into your application root folder. You can use the File Manager tile in your portal, SFTP via SSH Access, or an FTP client. Upload your custom source code and your package.json file. Do not upload your local node_modules folder, because compiled native binaries from your local machine will not match the server environment.

After uploading package.json, return to Setup Node.js App and perform a full page reload (hard refresh) in your browser. The tool checks disk contents on load. Once it detects package.json, the Run NPM Install button becomes active.

Click Run NPM Install to pull your dependencies into the server environment. If the build step fails or hangs, check that your package dependencies match the Node version you selected.

Setting environment variables

Do not commit secrets like database credentials or API keys directly to your repository. The Setup Node.js App screen provides a dedicated Environment variables table.

1. Click Add Variable at the bottom of your application settings.
2. Enter the key name and the value.
3. Click Done.
4. Click Save at the top of the interface.
5. Click Restart to apply the changes to the running process.

These values become available inside Node via process.env.YOUR_VARIABLE. If you are also executing commands manually over the terminal or writing automated scripts, review how variables behave across different process scopes in our guide on environment variables and export.

Troubleshooting startup errors and logs

If your app throws an unhandled exception during boot or fails to bind to process.env.PORT, LiteSpeed displays a 503 or 500 error in the browser.

Inspect the error output inside your application root. Startup crashes and runtime failures land in a log file named stderr.log inside the application root directory. You can open this file using the File Manager tile or read it in the terminal via SSH. The log captures unhandled promise rejections, syntax mismatches, and missing package imports.

Whenever you edit code files or modify variables, click the Restart button inside the Setup Node.js App manager to restart the lsnode worker.

When to contact support

If your application installs dependencies but consistently hangs without creating a stderr.log file, or if the runner fails to launch across restarts, reach out to support. Open the portal, navigate to Support, and open a new ticket. Include your application root path, the domain name, and your Support PIN (found under /account) so our team can investigate the process state.