Accueil / Articles / Déployer une application Node.js sur un hébergement partagé cPanel avec Passenger

Node.js cPanel Passenger Express Deployment Shared Hosting

Déployer une application Node.js sur un hébergement partagé cPanel avec Passenger

Un guide pas à pas pour exécuter une application Express sur un hébergement partagé cPanel avec Application Manager et Passenger, y compris les redémarrages, les variables d’environnement et les solutions pour les erreurs 503.

1265 mots

De nombreux hébergeurs partagés cPanel permettent de faire fonctionner correctement une application Express ou un serveur API, à condition que le compte dispose de la prise en charge de Node.js via Phusion Passenger derrière le Gestionnaire d’applications de cPanel. Vous n’avez pas à configurer vous-même Nginx, un proxy inversé Apache ou PM2 ; Passenger lance l’application et dirige les requêtes vers elle. Ce guide couvre le déploiement complet, de la vérification que cette fonctionnalité est activée à diagnostiquer un code 503, et se termine par une liste de contrôle avant le lancement.

Ce dont votre compte d’hébergement a besoin

Vérifiez que le compte offre ce qui suit avant de téléverser quoi que ce soit :

La prise en charge de Node.js
Le Gestionnaire d’applications cPanel
Passenger
Un accès au terminal ou par SSH
npm
Un domaine ou un sous-domaine depuis lequel servir l’application
Un accès à une base de données, si l’application en a besoin

Si le Gestionnaire d’applications est manquant, demandez à votre hébergeur d’activer Node.js et Passenger. Les hébergeurs utilisant CloudLinux pourraient nommer cet outil différemment.

Étape 1 : Vérifier que Node.js est disponible

Dans cPanel, ouvrez Software, puis Application Manager (dans certaines versions, les options Node.js se trouvent plutôt sous Gestion du site). S’il s’ouvre, le compte est prêt.

Étape 2 : Télécharger l’application

Téléchargez le projet à l’aide du Gestionnaire de fichiers ou de Git dans un dossier de votre répertoire personnel, par exemple :

/home/username/my-node-app

Un organisation typique d’un projet ressemble à ceci :

my-node-app/
├── package.json
├── package-lock.json
├── app.js
├── src/
└── ...

Conservez le code source en dehors de public_html, car les navigateurs peuvent demander directement tout ce qui s’y trouve.

Étape 3 : Préparer `package.json` et installer les dépendances

Le projet nécessite un package.json valide qui déclare ses dépendances ainsi qu’un script de démarrage. Voici un exemple minimal avec Express :

{
  "name": "my-node-app",
  "version": "1.0.0",
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "express": "^5.1.0"
  }
}

Ensuite, ouvrez le Terminal de cPanel, naviguez dans le dossier du projet et installez :

cd ~/my-node-app
npm install

Cela installe les dépendances déclarées sur le serveur. Avec un fichier de verrouillage enregistré, npm ci --omit=dev constitue une alternative plus légère et reproductible.

Étape 4 : Écrire le fichier de démarrage

Passenger a besoin d’un point d’entrée qu’il peut lancer, par exemple :

app.js

Pour une application Express, ce fichier commence par charger Express :

const express = require('express');

puis crée l’application, définit une route et commence à écouter. Le code ci-dessous est condensé en quelques lignes, mais il reste un JavaScript valide car chaque instruction se termine par un point-virgule.

const app = express();const PORT = process.env.PORT || 3000;app.get('/', (req, res) => {
    res.send('Node.js application is working!');
});app.listen(PORT, '0.0.0.0', () => {
    console.log(`Application running on port ${PORT}`);
});

Pourquoi le port doit provenir de `process.env.PORT`

Ne codez pas manuellement un port public. Passenger décide de la manière dont les requêtes atteignent votre processus, il est donc nécessaire de lire le port depuis l’environnement et d’avoir une solution de secours locale :

const PORT = process.env.PORT || 3000;

Le même code s’exécute ensuite localement sur le port 3000 ainsi que sous Passenger sans modification.

Étape 5 : Enregistrer l’application dans cPanel

Dans Application Manager, cliquez sur Créer une application ou Enregistrer une application. Donnez à l’application un nom tel que my-node-app, choisissez le domaine (par exemple example.com) et / comme URL de base, définissez le répertoire racine sur le dossier du projet et le fichier de démarrage sur app.js, sélectionnez une version stable de Node.js compatible avec vos dépendances, puis choisissez l’environnement Production. Cliquez ensuite sur Créer ou Déployer. Le chemin de la requête résultant ressemble à ceci :

https://example.com
       ↓
     Apache
       ↓
    Passenger
       ↓
   Node.js App
       ↓
     app.js

Apache reçoit la requête, et Passenger la transmet au processus Node.js lancé à partir de votre fichier de démarrage.

Étape 6 : Définir les variables d’environnement

Définissez les variables d’environnement dans les paramètres de l’application plutôt que dans le code. Par exemple :

APP_ENV=production
DB_HOST=localhost
DB_DATABASE=mydb
DB_USERNAME=myuser
DB_PASSWORD=your_password

Votre code les lit via process.env:

process.env.DB_HOST
process.env.DB_DATABASE
process.env.DB_USERNAME

Gardez les secrets uniquement du côté serveur : jamais dans le JavaScript frontend ou dans un fichier accessible publiquement tel qu’un .env dans public_html.

Étape 7 : Redémarrer après chaque modification

Passenger maintient l’application chargée, de sorte que les modifications ne s’appliquent qu’après un redémarrage depuis l’Application Manager. Lorsque la convention du fichier de redémarrage est prise en charge, le terminal fonctionne également :

mkdir -p ~/my-node-app/tmp
touch ~/my-node-app/tmp/restart.txt

Passenger surveille la date et l’heure de tmp/restart.txt et redémarre l’application lors de la prochaine requête après modification, ce qui convient aux scripts de déploiement.

Résolution d’un problème 503 Service Unavailable

L’erreur que vous rencontrerez le plus souvent est celle-ci :

503 Service Unavailable

Un 503 signifie rarement que le serveur est down ; généralement, Passenger n’a pas pu démarrer ou atteindre votre application. Exécutez-la vous-même en premier :

cd ~/my-node-app
node app.js

Si cela plante, corrigez d’abord ce problème. Si l’application démarre, vérifiez les causes habituelles.

Fichier de démarrage incorrect

Le Gestionnaire d’applications doit pointer vers le fichier qui existe réellement et permet de démarrer le serveur :

app.js

Dépendances manquantes

Si node_modules est absent ou incomplet, installez-le à nouveau :

npm install

Version de Node.js incompatible

Vérifiez quelle version utilise la terminal et quelles versions sont requises par vos dépendances :

node -v

Ensuite, choisissez une version compatible dans les paramètres de l’application.

Port codé en dur

Vérifiez que le serveur écoute sur :

process.env.PORT

plutôt que sur un port public fixe.

Variables d’environnement manquantes

Vérifiez que les identifiants, les clés API, le mode d’application et les autres valeurs nécessaires sont bien définis ; une variable non définie qui provoque un plantage au démarrage entraîne également un 503.

Journaux

Les journaux de l’application Passenger ou cPanel affichent généralement l’erreur d’exécution exacte.

Hébergement partagé contre VPS

Ces deux environnements diffèrent principalement par la personne qui contrôle le serveur. Dans l’hébergement partagé cPanel, la stack ressemble à peu près à ceci :

cPanel
   │
   ├── Apache
   ├── Passenger
   └── Node.js
          │
          └── Your Application

Le hébergeur et Passenger gèrent le serveur web et les processus. Sur un VPS, vous contrôlez chaque couche :

VPS
 │
 ├── Nginx/Apache
 ├── Node.js
 ├── PM2
 ├── Firewall
 ├── SSL
 └── Application

Un VPS offre un contrôle bien plus grand et convient généralement mieux aux applications gourmandes en ressources ou fortement personnalisées ; consultez un cadre pratique pour mettre en production des applications Node.js. L’hébergement partagé sacrifie ce contrôle au profit de la simplicité.

Une structure de répertoires ordonnée

Un déploiement cPanel bien organisé place l’application et la racine web publique côte à côte :

/home/username/
│
├── my-node-app/
│   ├── app.js
│   ├── package.json
│   ├── package-lock.json
│   ├── node_modules/
│   ├── src/
│   └── tmp/
│       └── restart.txt
│
└── public_html/

Les requêtes atteignent my-node-app via Apache et Passenger, et public_html reste exempt de code serveur.

Liste de contrôle finale

Node.js est activé pour le compte
Application Manager est disponible
une version compatible de Node.js a été sélectionnée
les fichiers du projet ont été téléchargés en dehors de public_html
package.json est présent
npm install s’est terminé sans erreurs
la configuration du fichier de démarrage est correcte
le serveur écoute sur process.env.PORT
les variables d’environnement sont configurées
l’environnement est réglé sur Production
l’application a été redémarrée depuis la dernière modification
le domaine s’affiche dans un navigateur

les journaux ne montrent aucune erreur de démarrage

Conclusion

Au sein d’un hébergement partagé cPanel, l’Application Manager avec Passenger constitue la solution fiable pour exécuter des applications Express et des API sans accès root. Laissez Passenger gérer le port, redémarrez après chaque modification, et en cas de problème, exécutez manuellement l’application et consultez les journaux avant de modifier la configuration.

Tous les articles Envoyer le brief