Archivio Domande

Overview

This guide walks you through creating, configuring and launching a Node.js application on your cPanel hosting account. It works for any Node.js framework: Express, Next.js, Nuxt, NestJS, Fastify, Koa, etc.

Estimated time: 5–10 minutes for a hello-world app, 15–30 minutes for a real app with dependencies.

Prerequisites

• Active hosting account with Node.js Selector enabled (all our shared and reseller plans include this).
• Your Node.js app source code (in a folder, or a git repo, or as a ZIP file).
• A domain or subdomain you want to point to the app.

Step 1 — Upload Your App Code

You have three options to get your code onto the server. Pick whichever you prefer:

Option A: ZIP Upload (easiest for beginners)

1. ZIP your project folder on your computer (skip node_modules — we'll install fresh on the server).
2. In cPanel → File Manager, navigate to your home directory.
3. Click Upload → select your ZIP.
4. Right-click the uploaded ZIP → Extract.
5. Note the folder name (e.g. myapp). You'll use this as the "Application Root".

Option B: Git Clone (recommended for production)

1. cPanel → Git Version Control → Create.
2. Tick Clone a Repository, paste your repo URL.
3. For private repos, set up an SSH deploy key first (cPanel → SSH Access).
4. Note the directory cPanel created (e.g. /home/user/repositories/myapp).

Option C: SSH/SFTP Upload

1. cPanel → SSH Access → generate or import an SSH key.
2. Connect via SSH or any SFTP client (FileZilla, WinSCP, Cyberduck).
3. Upload your project folder anywhere under /home/yourusername/.

Important: never put your Node.js app inside public_html. Keep it OUTSIDE web root for security. cPanel will route traffic into it via the Node.js Selector.

Step 2 — Create the App in cPanel

1. cPanel → under Software → Setup Node.js App.
2. Click Create Application.
3. Fill in the form:
   • Node.js version: latest LTS (currently 20.x recommended). Use the version your app needs.
   • Application mode: Production (use Development only for debugging).
   • Application root: the folder name from Step 1 (e.g. myapp) — this is RELATIVE to your home directory.
   • Application URL: the domain or subdomain that will serve the app. Leave the path empty for the site root, or add /api etc. for a subpath.
   • Application startup file: the entry file (e.g. server.js, app.js, index.js). For Next.js use server.js (you may need a custom one — see Step 5).
   • Passenger log file: leave blank, cPanel will auto-create.
4. Click Create.

cPanel will provision a Node.js virtual environment for your app. This takes 10–30 seconds.

Step 3 — Install Dependencies

Once the app is created, you'll see a panel with buttons. Find your app and click into it.

1. Click Run NPM Install. This reads your package.json and installs everything from npm.
2. Wait for it to finish — can take 30 seconds to 5 minutes depending on dependencies.
3. If it fails, check the error message. Common causes: missing package.json, native modules requiring build tools, version conflicts.

For private npm packages, set up .npmrc in your app root with your registry token before running install.

Step 4 — Set Environment Variables

Most production apps need configuration via environment variables (database credentials, API keys, etc.).

1. In the app management page, scroll to Environment variables.
2. Click Add Variable.
3. Enter the name (e.g. DATABASE_URL) and value.
4. Repeat for each variable.
5. Click Save.
6. Click Restart for the changes to take effect.

Don't store secrets in code. Use the env vars panel for anything sensitive. They're read by your app via process.env.VARIABLE_NAME.

Step 5 — Framework-Specific Setup

Express / plain Node.js

Make sure your entry file (e.g. server.js) listens on the port cPanel assigns:

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

Next.js

Next.js needs a custom server.js in your app root because cPanel calls it directly:

const { createServer } = require('http');
const next = require('next');

const app  = next({ dev: false });
const port = process.env.PORT || 3000;

app.prepare().then(() => {
  createServer((req, res) => app.getRequestHandler()(req, res))
    .listen(port);
});

Then build your app via Run NPM Script → build before the first restart. After that, only re-build when your source code changes.

Nuxt

Use node .output/server/index.mjs as your startup approach (or use a small launcher in server.js).

NestJS

Compile to dist/ via npm run build, then point cPanel's startup file to dist/main.js.

Step 6 — Start the App

1. Click Restart App (or "Start App" if it's the first run).
2. Visit your domain in a browser.
3. You should see your app load.

If you get a blank page or a 503 error, check the application log link in the cPanel panel for clues.

Step 7 — Updating Your App Later

For code changes:

1. Upload new files (FTP/Git/File Manager).
2. If you changed dependencies, click Run NPM Install.
3. If your framework needs a build (Next.js, Nuxt, NestJS), click Run NPM Script → build.
4. Click Restart App.

Critical: always use the Restart App button after changes. Never use "Run Script: start" — that hangs forever and locks your app management UI.

Common Mistakes (and How to Avoid Them)

Where to Get Help

• Check our "Node.js App Management — Troubleshooting" KB article first.
• Open a support ticket if your app won't start, with: app name, domain, error from logs, what you tried.