Contexte
L'hébergement web Winheberg fonctionne sous Plesk et prend en charge les applications Node.js, qu'il s'agisse d'une API, d'un backend ou d'un projet Next.js. Le déploiement diffère de celui d'un site PHP classique, car l'application tourne dans son propre processus géré par Phusion Passenger, et non comme un ensemble de fichiers servis directement par le serveur web.
Dès que vos fichiers sont en place, Plesk lit votre package.json, reconnaît le type d'application et propose une configuration automatique. Elle génère le fichier de démarrage attendu par Passenger et vous montre la liste des changements avant de les appliquer.
Ce guide suit ce parcours automatique, puis détaille la configuration manuelle pour les cas où la détection n'aboutit pas.
Prérequis
- Un hébergement web Winheberg actif
- Un accès à votre interface Plesk
- Les sources de votre application, avec son fichier
package.json - Un domaine ou sous-domaine déjà rattaché à l'hébergement, par exemple en suivant notre guide Comment relier un domaine externe à votre hébergement Plesk ?
L'accès SSH n'est pas disponible sur les hébergements web. Toutes les opérations décrites ici se font depuis l'interface Plesk, y compris les commandes npm.
1. Tester le projet en local
Avant tout envoi, vérifiez que votre application se construit et démarre sur votre machine.
npm install
npm run build
npm run start
Si l'une de ces commandes échoue en local, elle échouera également sur le serveur. Corrigez avant de continuer, le diagnostic est bien plus simple sur votre poste. Si votre projet n'a pas d'étape de build, seules la première et la dernière commande vous concernent.
2. Envoyer les fichiers de l'application
Compressez vos sources dans une archive .zip, sans les dossiers node_modules et .next. Ces dossiers seront régénérés sur le serveur, et leur envoi provoque des incompatibilités de plateforme en plus d'un transfert inutilement long.
Ouvrez Fichiers dans le menu latéral, placez-vous dans httpdocs, cliquez sur + puis Téléverser le fichier. Une fois l'archive envoyée, sélectionnez-la et extrayez-la sur place depuis le menu Archive.
Vérifiez qu'à la fin de l'extraction, le fichier package.json se trouve bien directement dans httpdocs et non dans un sous-dossier intermédiaire.
L'ordre de ces étapes compte. Plesk ne détecte le type d'application et ne propose la configuration automatique que si package.json est déjà en place. Sur un domaine vide, vous devrez tout renseigner à la main.
3. Lancer la configuration automatique
Depuis Sites Web & Domaines, ouvrez votre domaine, l'onglet Démarrer, puis Node.js. Plesk affiche le Type d'application détecté depuis package.json et le bouton Configurer automatiquement.
Cliquez sur Configurer automatiquement. Plesk liste ce qu'il va modifier avant de rien appliquer, par exemple la création du fichier de démarrage .plesk.startup.cjs qui charge votre point d'entrée, et la mise de côté d'un index.html statique qui serait servi à la place de votre application.
Relisez cette liste, puis cliquez sur Appliquer et redémarrer. Le fichier index.html d'origine est conservé sous le nom index.html.autoconfig-bak.
Inutile de changer le port écrit dans votre code. Passenger intercepte l'appel listen() de votre application et la branche sur son propre canal, quel que soit le port indiqué. Le fichier .plesk.startup.cjs le précise en commentaire, ne le modifiez pas et ne le supprimez pas.
4. Protéger vos fichiers source
Avec la configuration automatique, la Racine du document reste souvent la même que la Root d'application, c'est-à-dire /httpdocs. Le serveur web sert alors directement tout fichier présent dans ce dossier, y compris package.json et le code de votre application, que n'importe qui peut télécharger en connaissant son nom.
Plesk le rappelle d'ailleurs sur le tableau de bord tant que Node.js n'est pas activé, il recommande de définir la racine du document dans un sous-répertoire de la racine de l'application, par exemple public/.
Créez un dossier public dans httpdocs depuis le gestionnaire de fichiers. Sur le tableau de bord Node.js, cliquez ensuite sur l'icône de dossier à côté de Racine du document, sélectionnez public sous httpdocs dans l'arborescence, puis Enregistrer. Placez dans ce dossier uniquement les fichiers destinés à être servis tels quels, comme les images ou les feuilles de style.
N'écrivez jamais un mot de passe ou une clé d'API en dur dans votre code. Utilisez les Secrets de l'onglet Environnement, décrits à l'étape 8.
5. Vérifier la version et le mode d'application
Une fois la configuration appliquée, le tableau de bord affiche les boutons Redémarrer l'app, Arrêter l'app et Désactiver Node.js. Si le bouton Activer Node.js est encore présent, cliquez dessus.
Cliquez ensuite sur le crayon à côté de Version de Node.js, choisissez la version que réclame votre projet, puis Enregistrer. Contrôlez au passage que Mode d'application est bien sur production, c'est ce réglage qui fixe les variables NODE_ENV et PASSENGER_APP_ENV de votre application.
Quelle version choisir
Les versions proposées ne se valent pas. Une version LTS reçoit des correctifs de sécurité pendant plusieurs années, alors que les versions impaires comme 23.x ou 21.x ne sont jamais passées en LTS et ne sont plus maintenues.
| Version | Statut | Fin de support |
|---|---|---|
| 26.x | LTS actif depuis le 28 octobre 2026 | 30 avril 2029 |
| 24.x | LTS en maintenance depuis le 20 octobre 2026 | 30 avril 2028 |
| 23.x | Plus maintenue | 1er juin 2025 |
| 22.x | LTS en maintenance | 30 avril 2027 |
| 21.x | Plus maintenue | 1er juin 2024 |
| 20.x | Plus maintenue | 30 avril 2026 |
| 18.x | Plus maintenue | 30 avril 2025 |
Retenez une version 26.x pour un nouveau projet, c'est la branche LTS active. Gardez 24.x si l'une de vos dépendances n'est pas encore compatible, elle reste corrigée jusqu'en avril 2028.
Les branches 23.x, 21.x, 20.x et 18.x ne reçoivent plus de correctifs de sécurité. Évitez-les pour une application exposée sur Internet, même si votre code fonctionne avec.
Une version trop ancienne fait par ailleurs échouer le build de la plupart des frameworks récents, avec un message qui ne mentionne pas toujours la version en cause. Next.js 16 réclame par exemple Node.js 20.9 au minimum.
6. Installer les dépendances
Cliquez sur Installer NPM, ou ouvrez l'onglet Exécuter les commandes Node.js et choisissez install dans la liste. Plesk lit votre package.json et reconstruit le dossier node_modules sur le serveur.
La Sortie de la commande affiche le résultat. Attendez la fin de l'opération avant de passer à la suite, sur un projet volumineux l'installation prend plusieurs minutes.
Plesk prend aussi en charge Yarn et pnpm. Cliquez sur le crayon à côté de Gestionnaire de packages sur le tableau de bord pour choisir npm, yarn ou pnpm.
7. Lancer le build
Cliquez sur Démarrer le script. Plesk ouvre l'onglet Exécuter les commandes Node.js, dont la liste Scripts du package.json reprend les scripts de votre projet. Choisissez run build.
Pour un projet Next.js, cette étape génère le dossier .next, celui que vous n'avez volontairement pas envoyé. Construire sur le serveur plutôt que d'envoyer un build fait sur votre machine évite les incompatibilités d'architecture.
Pour Next.js, cette étape est obligatoire. Démarrer l'application sans build produit l'erreur Could not find a production build in the '.next' directory.
8. Déclarer les variables d'environnement
Ouvrez l'onglet Environnement. Il distingue deux types de valeurs transmises à votre application.
| Section | Usage |
|---|---|
| Variables d'environnement | Les réglages sans caractère sensible, visibles par toute personne qui ouvre cette page |
| Secrets | Les mots de passe, clés d'API et jetons, stockés chiffrés et en écriture seule, leur valeur n'est plus jamais affichée après l'enregistrement |
| Variables prédéfinies | NODE_ENV, PASSENGER_APP_ENV, NODE_PATH et IN_PASSENGER, définies par Passenger, une variable du même nom déclarée plus haut prend le dessus |
Ajoutez vos valeurs avec Ajouter un champ, cliquez sur Enregistrer, puis sur Redémarrer l'app depuis le tableau de bord pour que l'application les prenne en compte.
Avec Next.js, les variables préfixées NEXT_PUBLIC_ sont intégrées au code au moment du build. Placez-les dans un fichier .env.production à la racine de l'application avant de lancer l'étape 7, et réservez-y uniquement des valeurs que vous acceptez de rendre publiques.
9. Démarrer l'application
Cliquez sur Redémarrer l'app, puis ouvrez votre domaine dans un navigateur. Tant que personne ne l'a visitée, le Statut indique Inactif, l'application démarre à la première requête. Il passe ensuite à En cours d'exécution, avec le nombre de processus et l'heure de démarrage.
Configurer manuellement
Si votre package.json n'était pas en place au moment de l'activation, ou si la détection n'a pas reconnu votre projet, renseignez les champs vous-même depuis le tableau de bord Node.js.
| Champ | Valeur | Rôle |
|---|---|---|
| Root d'application | /httpdocs |
Le dossier qui contient le package.json |
| Racine du document | /httpdocs/public |
Le dossier des fichiers servis tels quels, distinct de vos sources |
| Fichier de démarrage d'application | Le fichier que Passenger exécute, app.js par défaut |
Le point d'entrée de votre application |
Passenger démarre un fichier JavaScript, il ne lance pas npm start. Lorsqu'une application se lance habituellement par une commande npm, ouvrez le package.json et repérez le fichier passé à node, c'est celui-là qu'il faut déclarer. Pour une application Express ou tout code Node.js écrit à la main, ce fichier existe déjà, souvent app.js, server.js ou index.js.
Pour Next.js, il n'existe pas. La commande next start appelle un binaire du framework et non un fichier de votre projet. Créez donc un fichier start.js à la racine de votre application, avec ce contenu.
process.env.NODE_ENV = 'production';
const app = require('next/dist/cli/next-start');
app.nextStart({
port: process.env.PORT || 3000,
});
Déclarez ensuite start.js dans Fichier de démarrage d'application, puis cliquez sur Redémarrer l'app.
Si votre package.json contient "type": "module", l'instruction require ci-dessus échoue. Nommez alors votre fichier start.cjs au lieu de start.js, l'extension .cjs force l'interprétation en CommonJS, puis déclarez ce nom dans le champ du fichier de démarrage.
En cas de problème
❌ Could not find a production build in the '.next' directory
Le build n'a pas été exécuté, ou il a échoué sans que vous l'ayez remarqué.
- Relancez
run builddepuis Démarrer le script et lisez la Sortie de la commande jusqu'au bout - Vérifiez que le dossier
.nextexiste dans la racine de l'application - Contrôlez que Root d'application pointe bien sur le dossier contenant le
package.json
❌ require() of ES Module is not supported
Votre projet est déclaré en module ES, ce qui rend l'instruction require inutilisable dans un fichier de démarrage en .js.
- Renommez votre fichier de démarrage avec l'extension
.cjs - Reportez ce nouveau nom dans Fichier de démarrage d'application
- Redémarrez l'application avec Redémarrer l'app
❌ The application process exited prematurely
Le processus n'a pas réussi à démarrer.
- Vérifiez que le fichier de démarrage existe réellement à la racine de l'application
- Assurez-vous que les dépendances ont bien été installées, la Sortie de la commande de
installne doit afficher aucune erreur - Recherchez une variable d'environnement ou un secret manquant dans l'onglet Environnement
- Confirmez que Mode d'application est bien réglé sur
production
❌ Vos fichiers source s'affichent dans le navigateur
La Racine du document est la même que la Root d'application, le serveur web sert donc vos sources directement.
- Créez un dossier
publicdans la racine de l'application - Définissez
/httpdocs/publiccomme Racine du document depuis le tableau de bord Node.js - Redémarrez l'application, puis ouvrez votre site en ajoutant
/package.jsonà la fin de son adresse, le fichier ne doit plus s'afficher
Bonnes pratiques
- Envoyez vos fichiers avant d'ouvrir la page Node.js, c'est ce qui permet la détection et la configuration automatique
- Validez toujours
npm run builden local avant d'envoyer quoi que ce soit - Gardez
node_moduleset.nexthors de vos envois, ils se régénèrent côté serveur - Relancez le build puis Redémarrer l'app après chaque mise à jour de votre code
- Restez sur une version LTS de Node.js et changez de branche avant sa fin de support
- Rangez les mots de passe et clés d'API dans les Secrets, jamais dans le code ni dans un fichier servi par le site
- Si vous changez de framework, relancez Configurer automatiquement pour que Plesk régénère le fichier de démarrage
- Servez votre application en HTTPS avec le certificat gratuit décrit dans notre guide Comment générer un certificat SSL Let's Encrypt pour votre site web ?
- Pour confier le déploiement à un développeur sans lui ouvrir tout votre compte, créez-lui un accès dédié avec notre guide Comment créer un utilisateur dans Plesk ?
Besoin d'aide ?
Si votre application ne démarre toujours pas après ces vérifications, ouvrez un ticket auprès de notre support depuis votre espace client, département Technique, en renseignant le champ Produit lié avec l'hébergement concerné.
Joignez le message d'erreur complet ainsi que la sortie du build. Notre équipe peut également consulter le journal de Passenger côté serveur, qui contient souvent la cause exacte d'un démarrage avorté.
Votre application est en ligne 🚀


