Déployer une application Node.js sur Plesk
Mettez en ligne une application Node.js depuis Plesk : structure des dossiers, fichier de démarrage, dépendances npm, variables d'environnement, journaux et résolution des erreurs courantes.
Sur cette page
Vos valeurs
Renseignez-les une fois, les commandes du guide se mettent à jour.
Ce guide explique comment publier une application Node.js sur votre domaine depuis Plesk, installer ses dépendances, la configurer puis vérifier qu'elle répond correctement.
Prérequis
- Un accès à votre panneau Plesk (voir Connexion à l'interface Plesk).
- Un domaine rattaché à votre hébergement et pointant vers celui-ci.
- Le code de votre application, avec son fichier
package.json. - Un moyen d'envoyer vos fichiers : le gestionnaire de fichiers de Plesk, un compte FTP ou un dépôt Git.
- Si votre application utilise une base de données MySQL ou MariaDB, une base créée dans Plesk.
Ce guide utilise httpdocs, le dossier habituel du domaine principal. Pour un domaine supplémentaire, le dossier peut être différent : reportez-vous à la Racine du document dans Hébergement et DNS > Hébergement.
Comprendre le fonctionnement
Sur Plesk pour Linux, votre application n'est pas lancée avec npm start ni avec un gestionnaire de processus comme PM2. C'est le serveur d'applications Phusion Passenger qui démarre le fichier indiqué dans Plesk et lui transmet les requêtes reçues par le serveur web.
Cela a trois conséquences pratiques :
- Le port est géré pour vous. Passenger ignore le numéro passé à
listen()et raccorde lui-même votre serveur HTTP. Vous n'avez aucun port à ouvrir ni à ajouter à l'adresse du site. - Le fichier de démarrage doit appeler
listen(), directement ou en chargeant le fichier qui le fait. - Le processus peut s'arrêter en cas d'inactivité, puis redémarrer à la requête suivante. Ne confiez donc pas une tâche récurrente à un minuteur interne (
setInterval) : utilisez plutôt les Tâches planifiées de Plesk.
Deux dossiers sont à distinguer :
| Réglage Plesk | Rôle | Exemple |
|---|---|---|
| Root d'application (Application Root) | Dossier contenant tout le projet : package.json, code, node_modules |
/httpdocs |
| Racine du document (Document Root) | Sous-dossier des fichiers publics, servis directement par le serveur web | /httpdocs/public |
La racine du document doit obligatoirement se trouver à l'intérieur du dossier de l'application. Seul son contenu est directement accessible depuis le web : vos fichiers .env, votre code et node_modules restent ainsi hors de portée, à condition de ne jamais les placer dans public.
Étape 1 : préparer l'application
Voici la structure utilisée dans ce guide :
httpdocs/
├── app.js
├── package.json
├── package-lock.json
└── public/
└── logo.pngSi vous souhaitez d'abord valider la configuration, ce fichier app.js minimal ne demande aucune dépendance :
const http = require('node:http');
const server = http.createServer((req, res) => {
res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
res.end('Application Node.js en ligne\n');
});
server.listen(process.env.PORT || 3000);Avec Express, le principe reste le même :
const express = require('express');
const app = express();
app.get('/', (req, res) => {
res.send('Application Node.js en ligne');
});
app.listen(process.env.PORT || 3000);Conserver process.env.PORT || 3000 permet au même code de fonctionner aussi sur votre poste de travail.
Vérifiez également votre package.json : les dépendances y sont listées, et les scripts que vous lancerez depuis Plesk doivent figurer dans la section scripts.
{
"name": "mon-application",
"version": "1.0.0",
"private": true,
"main": "app.js",
"scripts": {
"build": "echo \"Aucune compilation nécessaire\""
},
"dependencies": {
"express": "^5.0.0"
}
}Étape 2 : envoyer les fichiers
Envoyez le projet dans httpdocs, sans le dossier node_modules : les dépendances seront installées sur le serveur à l'étape 4.
La méthode la plus simple pour un premier envoi :
- Créez une archive
.zipde votre projet sur votre ordinateur. - Dans Plesk, ouvrez Fichiers (le gestionnaire de fichiers), puis le dossier
httpdocs. - Téléversez l'archive.
- Cochez-la, cliquez sur Extraire les fichiers, puis supprimez l'archive.
- Créez le dossier
publics'il n'existe pas : Plesk en a besoin comme racine du document, même s'il reste vide.
Étape 3 : configurer Node.js dans Plesk
-
Allez dans Sites Web & Domaines et repérez votre domaine.
-
Cliquez sur Node.js. Si le domaine n'a pas encore de site configuré, passez par Créer un site web > Node.js.
-
Renseignez les réglages :
Réglage Valeur à indiquer Version de Node.js La version attendue par votre application, ou la plus proche de celle utilisée en développement Gestion des Packs npmouYarn, selon votre projet. Plesk propose généralement le bon choixRacine du document /httpdocs/publicMode d'application productionune fois le site prêt,developmentpendant la mise au point. Cette valeur alimenteNODE_ENVRoot d'application /httpdocsFichier de démarrage d'application app.js, ou le fichier qui lance réellement votre serveur -
Validez avec OK si ce bouton est proposé.
Étape 4 : activer l'application et installer les dépendances
Toujours sur la page Node.js du domaine :
- Cliquez sur Activer Node.js.
- Cliquez sur Installer NPM (ou Yarn install). Ce bouton n'apparaît que si
package.jsonse trouve dans le dossier de l'application. - Si votre projet doit être compilé (TypeScript, front-end, etc.), cliquez sur Démarrer le script, saisissez le nom du script, par exemple
build, puis validez. - Cliquez sur Redémarrer l'app pour charger la dernière version.
Étape 5 : définir les variables d'environnement
Les clés d'API, mots de passe et autres réglages sensibles ne doivent pas figurer dans votre code.
- Sur la page Node.js, repérez Variables d'environnement personnalisées.
- Cliquez sur préciser, puis sur Ajouter une variable.
- Saisissez le nom et la valeur, par exemple
DATABASE_HOSTetlocalhost. - Validez, puis cliquez sur Redémarrer l'app.
Node.js ne charge pas automatiquement un fichier .env. Si votre application en utilise un, c'est à elle de le lire, par exemple avec le paquet dotenv.
Étape 6 : vérifier le résultat
Ouvrez https://votre-domaine.com/ dans votre navigateur. Avec l'exemple de ce guide, la page affiche Application Node.js en ligne.
Vous pouvez aussi contrôler la réponse depuis votre ordinateur :
curl -i https://votre-domaine.com/La première ligne doit indiquer le code 200. La première requête peut être plus lente, le temps que l'application démarre.
Pour consulter les messages de l'application, ouvrez Journaux depuis votre domaine, déroulez Tous les journaux et ne laissez cochée que l'entrée Node.js.
Mettre à jour l'application
- Envoyez les fichiers modifiés.
- Si
package.jsona changé, cliquez de nouveau sur Installer NPM. - Relancez votre script de compilation si nécessaire.
- Cliquez sur Redémarrer l'app.
Pour automatiser ces mises à jour, consultez Déployer depuis GitHub ou GitLab avec Plesk.
Dépannage
« Web application could not be started » ou « We're sorry, but something went wrong »
L'application a planté au démarrage. Ouvrez les Journaux pour lire l'erreur exacte, puis vérifiez :
- que le Fichier de démarrage d'application existe bien dans le Root d'application ;
- que les dépendances ont été installées ;
- que la version de Node.js correspond à celle attendue par le projet ;
- que toutes les variables d'environnement requises sont définies.
« The file does not exist » sur la page Node.js
Plesk ne trouve pas le fichier de démarrage. Contrôlez le Root d'application et le nom du fichier, en respectant les majuscules et minuscules.
Error: Cannot find module 'express'
Les dépendances sont absentes. Cliquez sur Installer NPM, vérifiez que le module figure bien dans dependencies et non uniquement dans devDependencies, puis redémarrez l'application.
ERR_REQUIRE_ESM ou « require() of ES Module not supported »
Passenger charge le fichier de démarrage avec require(), ce qui peut échouer lorsque votre projet utilise les modules ES ("type": "module" dans package.json). Créez dans le dossier de l'application un petit fichier passenger.cjs :
import('./app.js').catch((error) => {
console.error(error);
process.exit(1);
});Indiquez ensuite passenger.cjs comme Fichier de démarrage d'application, puis redémarrez.
L'application ne démarre pas et finit par expirer
Le fichier de démarrage n'appelle sans doute jamais listen(). C'est fréquent avec les projets créés par express-generator, où le serveur est lancé par bin/www et non par app.js. Indiquez alors le bon fichier, ou déplacez l'appel à listen().
Erreur liée à plusieurs serveurs HTTP
Passenger se raccorde au premier serveur qui appelle listen() et signale une erreur si l'application en crée plusieurs. Désignez explicitement le serveur à utiliser :
if (typeof PhusionPassenger !== 'undefined') {
PhusionPassenger.configure({ autoInstall: false });
}
const port = typeof PhusionPassenger !== 'undefined' ? 'passenger' : 3000;
server.listen(port);La page par défaut de Plesk ou une erreur 403 s'affiche
Vérifiez que Node.js est bien activé pour ce domaine et que la Racine du document pointe vers /httpdocs/public. Un ancien fichier index.html placé dans ce dossier serait servi à la place de votre application : supprimez-le ou renommez-le.
Les images ou feuilles de style renvoient une erreur 404
Les fichiers statiques doivent se trouver dans la Racine du document. Une URL /logo.png correspond au fichier public/logo.png, sans public dans l'adresse.
Vos modifications ne sont pas prises en compte
Node.js garde le code en mémoire. Cliquez sur Redémarrer l'app après chaque envoi de fichiers ou changement de variable.
Installer NPM échoue
Lisez le message affiché : il indique le paquet en cause. Vérifiez que la Version de Node.js respecte le champ engines de vos dépendances et que package-lock.json est à jour. Si l'erreur évoque un manque de mémoire ou la compilation d'un module natif, contactez le support depuis votre espace client en joignant ce message.