L'outil Applications de la console Apanel met en ligne une application web écrite en Node.js : vous choisissez la version de Node.js, l'adresse à laquelle l'application répond et le dossier qui contient son code. Le serveur la démarre avec Phusion Passenger, la relance si elle s'arrête et la relie à votre domaine. Le même outil sert aux applications Python et Ruby.
Si vous avez seulement besoin des commandes node et npm en SSH, par exemple pour compiler les fichiers JavaScript ou CSS d'un site, il n'est pas nécessaire de créer une application : voir la section Utiliser node et npm en SSH sans application, plus bas.
En bref : dans la Gestion de l'hébergement, carte Technologies web, cliquez sur Applications puis Ajouter une application : choisissez Node.js, la Version, l'URL et le répertoire. Installez ensuite les dépendances en SSH avec npm install, puis cliquez sur Redémarrer.
Prérequis
- Un hébergement qui inclut Node.js, sur l'un de nos serveurs récents : la tuile Applications apparaît alors dans la carte Technologies web de la Gestion de l'hébergement. Sur un serveur plus ancien, cette tuile ouvre une Demande de changement de serveur.
- Un accès SSH, pour installer les dépendances avec
npm install : voir Se connecter à votre hébergement en SSH.
Ce qu'il faut savoir avant de commencer
- C'est Passenger qui lance l'application. Votre code doit créer un serveur HTTP et appeler
listen(). Ne lancez pas node app.js vous-même en SSH : une application démarrée ainsi n'est pas reliée à votre domaine et n'est pas relancée en cas d'arrêt.
- Le code vit dans son propre répertoire, sous
~/apps/, à côté du dossier de votre site et non dedans.
- Passenger charge des modules CommonJS (
require). Une application écrite en modules ES (import) qui s'arrête sur ERR_REQUIRE_ESM doit être lancée par un petit fichier de démarrage .cjs qui l'importe : voir la documentation du Node.js Selector de CloudLinux.
- N'envoyez pas votre dossier
node_modules. Les dépendances s'installent sur le serveur avec npm install. Un dossier node_modules envoyé par vos soins est renommé node_modules.bak. suivi de la date quand vous enregistrez l'application.
- Supprimer une application efface son répertoire et tous les fichiers qu'il contient, sans retour possible.
Comment créer l'application Node.js ?
- Connectez-vous à votre console Apanel.
- Depuis le tableau de bord, cliquez sur le nom de votre domaine pour ouvrir la Gestion de l'hébergement. Pour une application sur un sous-domaine, cliquez sur le sous-domaine, dans le groupe Sous-domaines du tableau de bord.
- Dans la carte Technologies web, cliquez sur Applications.
- Cliquez sur Ajouter une application.
- Remplissez le formulaire Créer une nouvelle application (voir le tableau ci-dessous), puis cliquez sur Sauvegarder.
| Champ |
Ce qu'il faut y mettre |
| Langage |
Node.js. |
| Version |
La version de Node.js. La liste propose les versions installées sur votre serveur, la plus récente en premier. |
| URL |
L'adresse de l'application, après votre domaine affiché en gris : / pour la racine du domaine, /api pour votredomaine.ch/api. |
| Répertoire de l'application |
Le dossier du code, sous apps/. Il se remplit tout seul d'après l'URL : votredomaine.ch pour la racine, votredomaine.ch-api pour /api. |
| Fichier de démarrage |
Le fichier que Passenger exécute. Laissé vide, c'est app.js. |
| Environnement |
Développement par défaut. Choisissez Production pour un site en ligne : Passenger transmet ce choix à votre application dans la variable NODE_ENV. |
| Variables d'environnement |
Les réglages de votre application (clé d'API, adresse de la base de données) : un Nom de la variable et une Valeur de la variable par ligne, Ajouter une variable pour une ligne de plus. |
L'application est créée puis démarrée, et apparaît dans la liste Applications.
Comment envoyer le code et installer les dépendances ?
- Envoyez les fichiers de votre application dans son répertoire,
~/apps/ suivi du nom choisi, par FTP ou en SSH (par exemple avec git clone). N'envoyez pas node_modules.
- Dans la liste Applications, cliquez sur l'icône Comment utiliser ? de l'application. La fenêtre Travailler dans votre environnement via SSH affiche la commande qui entre dans le dossier de l'application et active sa version de Node.js. Copiez-la avec le bouton Copier.
- Connectez-vous en SSH et collez la commande. Elle ressemble à :
cd ~/apps/votredomaine.ch && source /home/votrecompte/nodevenv/apps/votredomaine.ch/22/bin/activate
- Installez les dépendances :
npm install
- Revenez à la liste Applications et cliquez sur Redémarrer.
Refaites les étapes 3 à 5 après chaque mise à jour du code.
Comment gérer l'application ?
Chaque ligne de la liste Applications indique :
- l'URL de l'application, avec une icône pour l'Ouvrir l'application dans un nouvel onglet ;
- son Statut : Running en vert, Stopped en rouge, Unknown en orange. À côté, les boutons Actualiser le statut, Démarrer, Arrêter, Redémarrer et Comment utiliser ? ;
- le Langage et la Version ;
- au bout de la ligne, Voir le journal de l'application, Editer et Supprimer.
Editer ouvre le formulaire Modifier l'application : vous pouvez y changer la version, l'URL, le fichier de démarrage, l'environnement et les variables. Le Langage et le Répertoire de l'application ne se modifient plus après la création : pour les changer, créez une nouvelle application.
Voir le journal de l'application affiche les dernières lignes écrites par votre application et par Passenger : c'est là que se lisent les erreurs de démarrage. La fenêtre permet de l'Actualiser, d'activer l'Actualisation automatique, de le Télécharger ou de le vider avec Vider le journal. En SSH, le même journal se trouve dans ~/logs/apps/.
Utiliser node et npm en SSH sans application
Pour compiler les fichiers d'un site ou lancer un script ponctuel, activez simplement une version de Node.js dans votre session SSH.
- Connectez-vous en SSH.
- Listez les versions disponibles sur votre serveur :
ls -d /opt/alt/alt-nodejs*
- Activez celle de votre choix, par exemple Node.js 22, et vérifiez-la :
source /opt/alt/alt-nodejs22/enable
node -v
node, npm et npx utilisent alors cette version jusqu'à la fin de la session. Pour l'activer à chaque connexion, ajoutez la ligne source /opt/alt/alt-nodejs22/enable à la fin du fichier ~/.bashrc.
Dans le dossier d'une application créée avec l'outil Applications, utilisez plutôt la commande de Comment utiliser ? : elle active la même version que l'application.
Un script qui doit tourner régulièrement (envoi de rapports, synchronisation) n'a pas sa place dans l'outil Applications, qui sert les sites web : lancez-le par une tâche planifiée, voir Programmer une tâche planifiée (cron).
En cas de problème
| Ce que vous voyez |
Ce qu'il faut faire |
| La tuile Applications n'apparaît pas |
Votre offre n'inclut pas Node.js. Contactez-nous pour la faire évoluer. |
| La tuile Applications ouvre une Demande de changement de serveur |
Votre hébergement est sur un serveur plus ancien, qui ne propose pas l'outil. Envoyez la demande pour être déplacé sur un serveur récent. |
| Cette URL est déjà utilisée par une autre application |
Une autre application du domaine répond déjà à cette adresse : choisissez une autre URL, ou modifiez l'autre application. |
Startup file '...' was not found in the application root (...) |
Le Fichier de démarrage indiqué n'existe pas dans le répertoire. Envoyez d'abord le fichier, puis enregistrez à nouveau. |
| Le fichier de démarrage est incorrect |
Le nom contient des caractères refusés : n'utilisez que lettres, chiffres, ., _, - et /. |
| Le statut reste Stopped, ou le site affiche une page d'erreur |
Ouvrez Voir le journal de l'application : la dernière erreur y est écrite (module manquant, erreur de syntaxe, ERR_REQUIRE_ESM). Corrigez, puis cliquez sur Redémarrer. |
Cannot find module dans le journal |
Les dépendances ne sont pas installées : activez l'environnement avec la commande de Comment utiliser ?, lancez npm install, puis Redémarrer. |
npm install échoue avec gcc, make ou node-gyp |
Un module doit être compilé sur le serveur. Contactez le support en joignant le message complet. |
Pour aller plus loin