Deploy a Node.js application on Plesk
Put a Node.js application online from Plesk: folder structure, startup file, npm dependencies, environment variables, logs and fixes for common errors.
On this page
Your values
Enter them once and the commands in this guide update.
This guide shows you how to publish a Node.js application on your domain from Plesk, install its dependencies, configure it and check that it responds correctly.
Prerequisites
- Access to your Plesk panel (see Connect to Plesk interface).
- A domain attached to your hosting and pointing to it.
- Your application code, including its
package.jsonfile. - A way to upload your files: the Plesk file manager, an FTP account or a Git repository.
- If your application uses a MySQL or MariaDB database, a database created in Plesk.
This guide uses httpdocs, the usual folder for the main domain. For an additional domain, the folder may be different: check the Document root under Hosting & DNS > Hosting.
How it works
On Plesk for Linux, your application is not started with npm start or with a process manager such as PM2. The Phusion Passenger application server starts the file you specify in Plesk and passes it the requests received by the web server.
This has three practical consequences:
- The port is handled for you. Passenger ignores the number passed to
listen()and connects your HTTP server itself. You have no port to open or to add to the site address. - The startup file must call
listen(), either directly or by loading the file that does. - The process can stop when idle, then restart on the next request. Do not rely on an internal timer (
setInterval) for a recurring task: use Plesk Scheduled Tasks instead.
Two folders need to be told apart:
| Plesk setting | Purpose | Example |
|---|---|---|
| Application Root | Folder containing the whole project: package.json, code, node_modules |
/httpdocs |
| Document Root | Subfolder for public files, served directly by the web server | /httpdocs/public |
The document root must be located inside the application folder. Only its contents can be reached directly from the web, which keeps your .env files, your code and node_modules out of reach, as long as you never place them in public.
Step 1: prepare the application
Here is the structure used in this guide:
httpdocs/
├── app.js
├── package.json
├── package-lock.json
└── public/
└── logo.pngIf you want to validate the configuration first, this minimal app.js file needs no dependencies:
const http = require('node:http');
const server = http.createServer((req, res) => {
res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
res.end('Node.js application online\n');
});
server.listen(process.env.PORT || 3000);With Express, the principle is the same:
const express = require('express');
const app = express();
app.get('/', (req, res) => {
res.send('Node.js application online');
});
app.listen(process.env.PORT || 3000);Keeping process.env.PORT || 3000 lets the same code run on your own computer as well.
Also check your package.json: it lists the dependencies, and any script you want to run from Plesk must appear in the scripts section.
{
"name": "my-application",
"version": "1.0.0",
"private": true,
"main": "app.js",
"scripts": {
"build": "echo \"No build required\""
},
"dependencies": {
"express": "^5.0.0"
}
}Step 2: upload the files
Upload the project to httpdocs, without the node_modules folder: the dependencies will be installed on the server in step 4.
The simplest method for a first upload:
- Create a
.ziparchive of your project on your computer. - In Plesk, open Files (the file manager), then the
httpdocsfolder. - Upload the archive.
- Select it, click Extract Files, then delete the archive.
- Create the
publicfolder if it does not exist: Plesk needs it as the document root, even if it stays empty.
Step 3: configure Node.js in Plesk
-
Go to Websites & Domains and find your domain.
-
Click Node.js. If the domain does not have a website set up yet, go through Create Website > Node.js.
-
Fill in the settings:
Setting Value to enter Node.js Version The version your application expects, or the closest one to the version used in development Package Manager npmorYarn, depending on your project. Plesk usually suggests the right choiceDocument Root /httpdocs/publicApplication Mode productiononce the site is ready,developmentwhile you fine-tune it. This value feedsNODE_ENVApplication Root /httpdocsApplication Startup File app.js, or the file that actually starts your server -
Confirm with OK if this button is shown.
Step 4: enable the application and install the dependencies
Still on the domain's Node.js page:
- Click Enable Node.js.
- Click NPM install (or Yarn install). This button only appears if
package.jsonis in the application folder. - If your project needs to be built (TypeScript, front end, etc.), click Run script, enter the script name, for example
build, then confirm. - Click Restart App to load the latest version.
Step 5: set the environment variables
API keys, passwords and other sensitive settings must not appear in your code.
- On the Node.js page, find Custom Environment Variables.
- Click specify, then Add variable.
- Enter the name and the value, for example
DATABASE_HOSTandlocalhost. - Confirm, then click Restart App.
Node.js does not load a .env file automatically. If your application uses one, it has to read the file itself, for example with the dotenv package.
Step 6: check the result
Open https://your-domain.com/ in your browser. With the example from this guide, the page displays Node.js application online.
You can also check the response from your computer:
curl -i https://your-domain.com/The first line should show the 200 status code. The first request may be slower while the application starts.
To read the application's messages, open Logs from your domain, expand All logs and leave only the Node.js entry selected.
Update the application
- Upload the modified files.
- If
package.jsonhas changed, click NPM install again. - Run your build script again if needed.
- Click Restart App.
To automate these updates, see Deploy from GitHub or GitLab with Plesk.
Troubleshooting
"Web application could not be started" or "We're sorry, but something went wrong"
The application crashed on startup. Open Logs to read the exact error, then check that:
- the Application Startup File exists in the Application Root;
- the dependencies have been installed;
- the Node.js version matches the one the project expects;
- all required environment variables are set.
"The file does not exist" on the Node.js page
Plesk cannot find the startup file. Check the Application Root and the file name, making sure upper and lower case match.
Error: Cannot find module 'express'
The dependencies are missing. Click NPM install, check that the module is listed in dependencies and not only in devDependencies, then restart the application.
ERR_REQUIRE_ESM or "require() of ES Module not supported"
Passenger loads the startup file with require(), which can fail when your project uses ES modules ("type": "module" in package.json). Create a small passenger.cjs file in the application folder:
import('./app.js').catch((error) => {
console.error(error);
process.exit(1);
});Then set passenger.cjs as the Application Startup File and restart.
The application does not start and eventually times out
The startup file probably never calls listen(). This is common with projects created by express-generator, where the server is started by bin/www rather than app.js. Specify the correct file, or move the listen() call.
Error related to multiple HTTP servers
Passenger attaches to the first server that calls listen() and reports an error if the application creates several. Explicitly designate the server to use:
if (typeof PhusionPassenger !== 'undefined') {
PhusionPassenger.configure({ autoInstall: false });
}
const port = typeof PhusionPassenger !== 'undefined' ? 'passenger' : 3000;
server.listen(port);The default Plesk page or a 403 error is displayed
Check that Node.js is enabled for this domain and that the Document Root points to /httpdocs/public. An old index.html file in this folder would be served instead of your application: delete or rename it.
Images or stylesheets return a 404 error
Static files must be located in the Document Root. A /logo.png URL maps to the public/logo.png file, without public in the address.
Your changes are not taken into account
Node.js keeps the code in memory. Click Restart App after each file upload or variable change.
NPM install fails
Read the message displayed: it names the package at fault. Check that the Node.js Version meets the engines field of your dependencies and that package-lock.json is up to date. If the error mentions a lack of memory or the compilation of a native module, contact support from your client area and include this message.