Setup NodeJS App : Déployer une application NodeJS

L'outil Setup Node.js App permet de déployer une application web conçu avec nodeJS. L'outil vous permet de créer un projet nodejs, il permet de :

  • Choisir la version de NodeJS que va utiliser votre projet. A cet instant, les versions 6, 8, 9, 10, 11 et 12 de NodeJS sont proposés.
  • Faire le lien entre un de vos noms de domaines et votre application. En arrière plan, l'outil utilise Phusion Passenger pour faire cela.
  • Installer vos dépendances à partir de l'outil (qui va utiliser NPM pour cela)
  • Un environnement NodeJS va être créé, avec la version de votre choix. Une commande sera donné permettant d'entrer dans cet environnement pour travailler en SSH

Pour faire simple, c'est l'outil à utiliser si vous souhaitez installer une application web conçu avec NodeJS sur un hébergement web o2switch.

Icône Nom Catégorie Description
Setup Node.js App Logiciel Permet de déployer une application web conçu avec NodeJS

Exécutable node et npm

Si vous avez juste besoin des exécutable node et npm, par exemple pour installer les dépendances d'un projet (qui n'est pas forcément un projet nodeJS complet), vous pouvez regarder : Comment utiliser les commandes node et npm sur l'hébergement ?
Il n'est pas nécessaire de créer un projet nodeJS avec l'outil setup nodejs app si vous avez juste besoin des exécutables node et npm.

L'outil Setup nodeJS app contient trois pages essentielles :

  • La page d’accueil de l'outil va lister les applications nodeJS qui sont déjà déployées sur l'hébergement
  • La page de création va permettre de créer une nouvelle application et environnement nodeJS
  • Enfin, il y a la page d'édition et de gestion des applications nodeJS déjà déployées

Sur la page d’accueil de l'outil, vous retrouverez la liste de vos projets nodeJS ainsi que le bouton de création d'un nouveau projet nodejs.

Liste des projets nodeJS déployés sur l'hébergement

Page d'accueil de l'outil Setup NodeJS app qui liste les projets déployés

  1. Le premier bouton Create Application lance l'assistant de création d'un nouveau projet nodeJS (détaillé plus loin)
  2. La colonne App URI indique sur quel nom de domaine / URL est déployé le projet nodeJS
  3. App Root Directory indique dans quel dossier se trouve les sources nodeJS du projet. C'est le dossier qui contient le code de l'application
  4. Status indique si le projet de lancé ou stoppé. Contrairement à une application PHP par exemple, un projet nodeJS doit être lancé et peut être stoppé
  5. c'est le bouton pour stopper l'application
  6. est le bouton permettant de relancer totalement l'application
  7. est le bouton permettant d'éditer une application, cela rouvre l’assistant de création d'une application node et permet de changer les configurations
  8. est le bouton permettant de supprimer l'application

L'écran suivant est le formulaire de création d'une application nodeJS qui s'affiche après avoir cliqué sur Create Application.

Déploiement d'une application nodeJS sur un hébergement o2switch

Déploiement d'une application NodeJS avec l'outil Setup NodeJS App

  1. Create : valide la création de l'application, à utiliser après avoir rempli le formulaire.
  2. Node.js version : permet de choisir la version de nodeJS que va utiliser votre projet. Vous avez le choix entre les versions 6, 8, 9, 10, 11, 12 (à l'heure de la rédaction de cette page)
  3. Application mode : permet de choisir entre le mode de développement et le mode de production. Va remplir la variable NODE_ENV.
  4. Application root : il s'agit du dossier dans lequel se trouve les sources de votre application node. Généralement il s'agit d'un dossier à créer à la racine de l'hébergement (recommandé). Ce dossier n'est pas forcément le même dossier que le dossier dans lequel va pointer le nom de domaine !
  5. Application URL : permet de définir l'url de l'application, en choisissant le domaine sur lequel l'application va répondre et le sous dossier dans lequel cela va être installé (peut être vide pour une application installé directement sur le nom de domaine)
  6. Application startup file : il faut définir le fichier .js qui sert à lancer l'application. Ce fichier doit être présent dans le dossier définie dans Application Root. Il s'agit souvent d'un fichier server.js
  7. Passenger log file : il s'agit du fichier de log que va créer Phusion Passenger, qui est le moteur d'exécution de nodeJS utilisé sur l'hébergement. Utile pour le débug.
  8. Add Variable permet de créer des variables d'environnements, vous pouvez passer des paramètres à votre application de cette manière là

Application root et document root du nom de domaine

Le dossier Application root du projet nodeJS est le dossier qui contient les fichiers sources de l'application nodeJS. Généralement, il s'agit d'un dossier à créer à la racine de l'hébergement, c'est ce qui est recommandé.

Il ne faut pas confondre ce dossier là avec le document root ou la racine du document du nom de domaine. Il s'agit du dossier dans lequel pointe le nom de domaine. L'application nodeJS peut être dans un dossier différent du domaine !

Exemple : l'application nodeJS se trouve dans /mon-application-node et le nom de domaine associée à cette application peut pointer dans /mon-domaine.tld. A la racine du dossier /mon-domaine.tld, l'outil setup nodejs app va créer un .htaccess permettant de faire le lien entre l'application nodeJS et le nom de domaine. Les sources de l’application n'ont pas besoin de se trouver dans le dossier du domaine, il faut même éviter cela ! (les sources pouvant être accessibles et télécharger librement lorsque l'application est stoppée !)

L'écran suivant de l'application est accessible en cliquant sur le bouton en forme de crayon visible sur la page d’accueil de l'outil, cela permet d'éditer une application existante.

Edition d'une application nodejs existante

Formulaire d'édition d'une application nodeJS qui est déjà déployée

Dans l'ordre, voici le détails de chaque option :

  1. Destroy permet de supprimer l'application
  2. Save permet d'enregistrer les changements que vous avez fait
  3. Source la commande commençant par source est très importante. Si vous travaillez en SSH, il faut lancer cette commande pour entrer dans votre environnement NodeJS. Si vous ne lancez pas cette commande, vous ne serez pas dans votre environnement nodeJS et par conséquent les commandes comme node ou npm ne seront pas trouvées.
  4. Stop App permet d'arrêter l'application
  5. Restart permet de relancer l'application, utile si vous faites des modifications sur votre application, un restart sera nécessaire
  6. Node.js version permet de choisir/changer la version de NodeJS que votre projet utilise
  7. Application mode permet de passer l'application en mode de développement ou en mode de production
  8. Application root correspond au chemin dans lequel se trouve les fichiers sources de votre application node. Généralement cela correspond à un dossier à la racine de votre hébergement. Ce dossier là est souvent différent du dossier avec lequel peut être associé le nom de domaine.
  9. Application URL permet de choisir sur quelle URL répondra l'application
  10. Application startup file est le fichier, contenu dans le dossier défini par le Application root qui permet de lancer l'application. Il s'agit souvent d'un fichier server.js ou index.js
  11. Passenger log file est le chemin vers le fichier de log que va utiliser Phusion Passenger qui correspond à la technologie utilisée pour proposer nodeJS en contexte mutualisé
  12. Detected configuration files : détecte les fichiers de configuration à la racine de votre projet nodeJS (package.json) et lance npm pour installer les dépendances
  13. Add Variable vous permet de passer des variables d'environnement à votre application, pour passer la configuration par exemple

Pour prendre un exemple concret et montrer comment déployer une application nodejs, nous allons installer l'application Ghost avec l'outil Setup NodeJS App.

On va suivre la documentation officielle de Ghost et installer Ghost en utilisant l'utilitaire ghost-cli

La première chose à faire est donc de créer un environnement NodeJS afin que nous puissions installer ghost-cli et ensuite l'utiliser pour installer Ghost. Pour cette raison, on commence par créer un environnement vide, juste pour qu'on puisse avoir accès aux commandes node et npm pour installer ghost-cli.

Création d'un projet vide

Création d'un projet vide, pour installer Ghost-CLI et ensuite Ghost

Projet vide

En créant un projet vide, c'est-à-dire sans mettre de fichiers sources nodejs et sans remplir le application startup file, l'outil setup nodejs app va quand même créer un environnement nodejs et placer un hello world d'exemple.

La création d'un projet vide peut être utile pour créer l'environnement nodeJS et ensuite travailler dans cet environnement en SSH, comme nous allons le faire ici avec ghost-cli.

Une fois le projet vide créé, on a accès à la commande source qui permet d'entrer dans l'environnement nodeJS en SSH ou avec l'outil terminal de cPanel.

Page du projet nodeJS sur setup nodejs app o2switch

Le projet nodeJS est créé, l'environnement est accessible avec la commande source

Ensuite, il faut copier/coller la commande source et la lancer dans l'outil terminal ou en SSH. La commande doit ressembler à cela :

source /home3/o2dev/nodevenv/mon-app-node-ghosts/10/bin/activate && cd /home3/o2dev/mon-app-node-ghosts

Une fois présent dans l'environnement, il faut lancer la commande npm install ghost-cli@latest -g pour installer l'exécutable qui permet d'installer Ghost facilement.

Environnement nodeJS en SSH ou dans le terminal

Environnement nodeJS en SSH et installation de ghost-cli

On constate que le prompt du shell change suite au lancement de la commande source. C'est mis en avant en bleu dans la capture d'écran, c'est à cela que l'on reconnait que l'on se trouve bien dans l'environnement nodeJS.

L'utilitaire d'installation de Ghost est à présent bien installé mais dans un répertoire qui n'est pas dans le PATH. Autrement dit, la commande ghost n'est pas accessible directement, il faut donc mettre à jour temporairement le PATH pour utiliser la commande ghost sans devoir taper le chemin absolu vers la commande.

Il faut également supprimer le contenu du dossier de l'application vide créée : cela contient le hello world installé par l'outil setup nodejs app. Un dossier vide est nécessaire pour l'installation de Ghost.

# On met à jour le PATH pour accéder à l'utilitaire ghost
export PATH="$PATH:/home3/o2dev/nodevenv/mon-app-node-ghosts/10/lib/bin/"
# On supprime l'application hello world créé par l'outil setup nodejs app 
rm -fr app.js node_modules/ public/ tmp/
# On installe Ghost 
ghost install local

Installation de Ghost avec l'utilitaire ghost-cli

Installation de Ghost avec la commande ghost-cli

Cela indique que l'application est lancée mais en réalité, ça ne fonctionnera pas, pour plusieurs raisons :

  • L'application écoute sur un port particulier, sur localhost. Ce n'est pas valide, il faudra ajuster une configuration pour rectifier cela.
  • En interne, l'application Ghost pense qu'elle est en localhost, les liens générés seront sur des adresses de la forme localhost/quelquechose. Une configuration dans Ghost est nécessaire pour corriger cela.
  • Et surtout, nous n'avons pas encore mis à jour le projet dans setup nodejs app donc pour le moment le application root est invalide.
  • Il faudra également tuer l'application qui a été lancée manuellement, en dehors de Phusion Passenger

Dans un premier temps, on corrige la configuration de l'application Ghost :

# On édite le fichier de configuration de Ghost, qui se trouve à la racine du projet
vi config.development.json
# A changer dans la configuration : 
# - url : pour passer de localhost vers http://demo.o2dev.fr
# - port : on laisse vide
# - host : on remplace localhost par 'passenger' qui est un mot clé particulier pour faire le lien avec phusion passenger
 
# Ensuite on tue l'application qui a été lancé manuellement, on commence par récupérer son PID
ps -ef
# on tue l'application avec le PID trouvé
kill -9 570806

Ajustement dans la configuration de Ghost

Ajustement dans la configuration de Ghost : définition du domaine et l'hôte passenger

Maintenant, il ne reste plus qu'à mettre à jour le application root dans l'outil setup nodejs app, pour mettre le point d'entré de Ghost et l'installation sera terminée !

Ajustement de la configuration dans l'outil setup nodejs app

Mise à jour des paramètres du projet nodeJS dans l'outil setup nodejs app

Installation d'une application nodejs o2switch

Installation de l'application nodeJS Ghost sur un hébergement o2switch

L'exemple de Ghost est un peu particulier car il s'installe avec un exécutable ghost-cli.

Sur un projet que vous développez, le processus d'installation est généralement différents car vous n'avez pas d'utilitaire comme ghost-cli. Le processus ressemble plutôt à :

  1. Vous envoyez les données de votre application dans un dossier à la racine de votre hébergement. En FTP, avec GIT ou en SSH.
  2. Vous créez le projet nodejs avec l'outil setup nodejs app dans cPanel :
    • Il faudra choisir la version de NodeJS à utiliser avec la partie NodeJS version. La version de node à choisir dépendra de votre projet.
    • Il faudra également choisir sur quel nom de domaine/URL répondra l'application, avec la partie Application URL
    • Le application root correspondra au dossier dans lequel se trouve les sources de l'application (créé précédemment).
    • Le application startup file correspondra au fichier qui lance votre application (index.js, server.js, app.js)
  3. Ensuite il faudra installer les dépendances avec NPM, soit avec l'interface graphique qui détecte le package.json, soit en SSH ou le terminal en lançant la commande source puis la commande npm
  4. Enfin, il suffit de lancer l'application (après avoir configuré l'application si cela est nécessaire)

Pour éviter que cette page devienne trop longue, voici d'autres tutoriels pour l'installation d'applications nodeJS fréquemment utilisé :

L'une des plus grandes difficultés dans l'utilisation de cet outil est de comprendre comment est lancé l'application qui est déployée.

En effet, si vous avez suivi l'un des guides d'installation, vous constatez qu'a aucun moment on ne lance de commande node server qui permet de lancer le serveur nodeJS.

De la même manière, nous n'avons pas évoqué le port d'écoute de l'application. Généralement, une application node écoute sur le port 3000. Que se passe t'il si ce port est déjà utilisé ? Après tout, cela est possible si deux personnes essayent de lancer une application node avec le réglage par défaut.

En réalité, c'est Phusion passenger qui s'occupe de tout cela en arrière plan. Vous n'avez pas besoin de vous soucier de Phusion passenger directement car l'outil Setup nodeJS app fait les réglages pour vous. Cependant, c'est quand même intéressant de voir et comprendre comment se lance réellement l'application node, cela évitera des erreurs.

Phusion passenger est un serveur web applicatif, c'est lui qui va être responsable de lancer votre processus NodeJS. Il fait donc l’intermédiaire entre le serveur web, qui traite les requêtes HTTP et votre application.

C'est pour cette raison qu'il ne faut pas lancer votre application nodeJS manuellement, vous même. Si vous lancez l'application vous même :

  • vous allez binder l'application avec un port, par exemple le port 3000. Si le port est déjà utilisé, ça renverra une erreur.
  • le port 3000 ne sera pas accessible depuis l'extérieur car ce n'est pas un port standard autorisé sur le parefeu du serveur. Donc impossible d'utiliser http://mondomaine.tld:3000 par exemple
  • vous ne pourrez pas faire le lien entre votre application et un nom de domaine, pour par exemple faire en sorte que lorsqu'on se rend sur “http://mondomaine.tld”, ce soit l'application node lancé qui réponde
  • si votre processus nodeJS plante, il n'y aura rien pour le relancer

C'est le rôle de Phusion Passenger de faire cela, il va :

  • lancer votre application et faire en sorte qu'il n'y a pas de conflit d'utilisation avec le port d'écoute de l'application (voir plus loin pour le détail)
  • relancer votre application si cette dernière ne répond pas
  • faire le lien entre votre application et un domaine de votre hébergement

Concernant le port d'écoute, lorsque vous application démarre, PhusionPassenger va attendre un appel à la fonction listen() de http.Server. Il se greffe dessus en quelque sorte.

Si votre application ne fait jamais appel à listen(), cela se terminera en erreur de timeout. Si cela arrive, deux cas sont possible :

  • soit il y a un problème avec l'application car elle n'appelle jamais listen()
  • ou vous ne cherchez probablement pas à lancer une application web nodeJS mais une application permettant de faire autre chose, comme un bot par exemple. Dans ce cas, vous pouvez utiliser l'outil setup nodejs app pour créer l'environnement virtuel node, gérer vos dépendances mais il ne faudra pas lancer l'application à partir de l'outil cPanel car c'est uniquement prévu pour une application web. Il faudra lancer votre application manuellement et prévoir un mécanisme de relance automatique si le processus meurt (via une cron par exemple)

Dés que l'appel à listen() est fait, PhusionPassenger va automatiquement faire en sorte que l'application n'écoute pas sur un port classique mais va forcer l'utilisation d'une Socket Unix à la place. Cela évitera tout conflit de port déjà utilisé.

En résumé, le paramètre que vous passez à la fonction listen() de votre application est totalement ignoré. C'est comme si vous lanciez listen(socketUnix).

Après, c'est PhusionPassenger qui se débrouille pour utiliser cette socket unix et faire le lien avec le serveur web.

Ce mécanisme se nomme le Reverse port binding et est documenté ici : Reverse port binding in Node.js.

Normalement tout ce processus est géré automagiquement par PhusionPassenger, sans modifications nécessaires dans l'application, sauf dans des cas très rares documentés dans le lien ci-dessus (multiple appels à listen() par exemple). Par exemple Express.js, Hapi.js peuvent être concernés par ce problème. Pour ces cas rares, il faut faire 2-3 modifications dans l'application pour aider PhusionPassenger dans son choix.

Il est possible de déployer intégralement une application nodeJS en ligne de commande. Cela dépasse le cadre de cette documentation, mais vous pouvez utiliser la commande cloudlinux-selector qui est documentée ici.

Cela peut être utilisé lors d'un déploiement automatique, via GIT par exemple.

Voici quelques solutions ou pistes de recherches pour les erreurs courantes en rapport avec le déploiement d'applications nodeJS.

En cas d'erreurs, la page d'erreur qui s'affiche (dans le navigateur web) ne contient pas beaucoup d'information par défaut. Il est possible d'activer le mode de debug avancé de Phusion Passenger, la page d'erreur générée sera beaucoup plus complète.

Pour cela, il suffit d'ajouter les lignes suivantes dans le fichier .htaccess à la racine du site internet :

PassengerAppEnv development
PassengerFriendlyErrorPages on

Les erreurs sont également loguées dans l'outil erreurs de cPanel.

Si l'application ne se lance pas et part en erreur timeout après environs 90 secondes, cela signifie que passenger n'arrive pas lancer votre application. Cela est expliqué plus en détails dans la partie Comment passenger lance l'application ?

Pour faire simple, passenger attend et surveille l'appel à la fonction listen() de http.Server. Il va l'intercepter, pour faire le lien entre votre application et le serveur web.

Dans 90% des cas, cela se passe correctement, sans réglage supplémentaire nécessaire. Mais passenger peut avoir du mal à faire cela si :

  • votre application contient plusieurs appels différents à la fonction listen() de http.Server. Dans ce cas, passenger ne sait pas sur quel listen() il doit se greffer. Dans ce cas, il faut faire des ajustements dans l'application pour aider passenger à faire son choix.
  • votre application ne fait pas d'appel à listen(). Généralement cela signifie que votre application n'est pas une application web nodeJS (autrement dit, ce n'est pas un site). Par exemple, il s'agit d'un bot. Dans ce cas, l'application ne peut pas être lancée avec passenger et c'est l'un des rares cas ou l'application peut être lancée manuellement avec la commande node. Il faudra prévoir un moyen de relancer le processus s'il est interrompu.

Pour aider passenger à faire son choix, il faut remplacer le port dans listen() par le mot clé spécial passeger ou /passenger dans le cas de hapi.js. Ci-dessous des exemples (issue de la documentation de passenger).

Application générique avec passenger
// Remplacer 
app.listen(3000);
// Par 
app.listen('passenger');
 
// ou plus générique/dynamique
// en détectant si PhusionPassenger est actif
if (typeof(PhusionPassenger) !== 'undefined') {
    PhusionPassenger.configure({ autoInstall: false });
}
 
if (typeof(PhusionPassenger) !== 'undefined') {
    app.listen('passenger');
} else {
    app.listen(3000);
}
express.js avec passenger
if (typeof(PhusionPassenger) !== 'undefined') {
    PhusionPassenger.configure({ autoInstall: false });
}
 
var express = require('express');
var app = express();
app.get('/', function(req, res) {
    var body = 'Hello World';
    res.setHeader('Content-Type', 'text/plain');
    res.setHeader('Content-Length', body.length);
    res.end(body);
});
 
if (typeof(PhusionPassenger) !== 'undefined') {
    app.listen('passenger');
} else {
    app.listen(3000);
}
Hapi.js avec /passenger
if (typeof(PhusionPassenger) !== 'undefined') {
    PhusionPassenger.configure({ autoInstall: false });
}
 
var Hapi = require('hapi');
var server;
 
if (typeof(PhusionPassenger) !== 'undefined') {
    // Requires Passenger >= 4.0.52!
    server = new Hapi.Server('/passenger');
} else {
    server = new Hapi.Server('localhost', 3000);
}
 
server.route({
    method: 'GET',
    path: '/hello',
    handler: function (request, reply) {
        reply('hello world');
    }
});
 
server.start();
  • Dernière modification: il y a 5 semaines
  • par o2switch