Node.js applications

A Gen2 server runs Node.js applications as well as PHP ones. Each Node.js application runs as its own service under its own Linux user, restarts by itself if it stops, and gets the domain's traffic over HTTPS through nginx.

Create one

1. Open Applications on the server

   In New application, choose the platform Node.js and a Node.js version (22 is the long-term support release).

2. Create it

   If that Node.js version is not on the server yet, it is installed first (under a minute). The application starts at once with a welcome page and gets its SSL certificate.

3. Deploy your code

   Connect your repository on the Git deploys tab. Each deploy runs npm ci (or npm install without a lock file), npm run build when there is a build script, switches to the new release and restarts the app.

What your app needs

• Listen on process.env.PORT (and 127.0.0.1). The server gives every Node.js application its own local port.
• A start command: npm start by default, so a start script in package.json. Change it on the Node.js tab, for example node server.js or npm run start.
• For Next.js: next start reads PORT by itself, so the default npm start works.

The Node.js tab

• Status: running or not, memory, how long it has been up, and a Restart button.
• Version and start command: switch between Node.js 20, 22 and 24. A version not on the server yet is installed first.
• Environment variables: one KEY=value per line. Saving restarts the app.
• Log: the latest lines your app writes to the console, newest first.

When it does not start

You see	Usually
502 Bad Gateway on the site	The app is not running or listens on another port. Check the log on the Node.js tab and make sure it uses process.env.PORT.
The status keeps switching to Starting	The start command fails right away. The log shows the error, often a missing build (npm run build) or a missing variable.
Cannot find module	Dependencies are missing. Deploy again from Git so npm ci runs, or check that the module is in dependencies.