Déployer une application Node.js sur SwissCenter (Apanel / CloudLinux)

1. Introduction

L'outil Applications de l'Apanel SwissCenter permet de déployer une application web conçue avec Node.js. Il utilise Phusion Passenger en arrière-plan pour faire le lien entre votre application, le serveur web Apache/Nginx et les noms de domaine.

L'outil vous permet de :

• Choisir la version de Node.js que va utiliser votre projet (versions 6, 8, 9, 10, 11, 12, 14, 16, 18, 19, 20, 22 et 24 disponibles)
• Définir l'URL d'accès à votre application (ex: /mon-app)
• Définir le répertoire source et le fichier de démarrage
• Installer vos dépendances NPM
• Gérer les variables d'environnement
• Créer un environnement virtuel Node.js accessible en SSH

2. Différence entre frontend et backend

⚠️ Important : Si vous avez juste besoin des exécutables node et npm (par exemple pour compiler des assets React, Vue.js ou autre), il n'est pas nécessaire de créer une application avec l'outil Applications. Utilisez plutôt l'Accès SSH pour exécuter les commandes directement.

3. Accès à l'outil Applications

1. Connectez-vous à votre Apanel : https://apanel.swisscenter.com
2. Depuis le tableau de bord, cliquez sur le nom de votre domaine

3. Dans la section Gestion de l'hébergement, repérez la catégorie Technologies web
4. Cliquez sur Applications

4. Créer une nouvelle application Node.js

Depuis la page Applications, cliquez sur AJOUTER UNE APPLICATION.

Remplissez le formulaire avec les paramètres de votre projet :

Champs du formulaire

Recommandations importantes

• Application Root ≠ Document Root : Le dossier source de l'application (apps/myapp) doit être différent du dossier racine du domaine. Le lien est fait automatiquement par l'Apanel via des règles Apache.
• Fichier de démarrage : Ce fichier (app.js, server.js, index.js…) doit être présent dans le répertoire défini ci-dessus.
• Sous-domaine : Pour déployer sur un sous-domaine (ex. nodejs.votresite.ch), laissez l'URL à / (racine) et le répertoire devient apps/nodejs.votresite.ch.

5. Liste des applications et gestion

Après la création, votre application apparaît dans la liste :

Boutons d'action

• ▶️ (Play) — Démarrer l'application
• ⏹️ (Stop) — Arrêter l'application
• 🔄 (Restart) — Redémarrer l'application (après modification du code)
• ✏️ (Edit) — Modifier la configuration de l'application
• 🗑️ (Supprimer) — Supprimer définitivement l'application

6. Déployer les fichiers de l'application

L'application créée génère automatiquement :

• Un squelette app.js dans le répertoire choisi
• Les dossiers public/ et tmp/

Via l'Explorateur de fichiers

1. Depuis la Gestion de l'hébergement, allez dans Outils > Explorateur de fichiers
2. Naviguez jusqu'à votre dossier d'application (ex: /apps/myapp)
3. Cliquez sur le fichier app.js pour l'éditer
4. Remplacez le contenu par votre code serveur
5. Cliquez sur Sauvegarder

Via SSH

1. Activez l'Accès SSH dans la section Site web
2. Connectez-vous à votre serveur :

   ssh votresite@web24.swisscenter.com

3. Activez l'environnement virtuel Node.js :

   source ~/nodevenv/apps/myapp/20/bin/activate

   Commande récupérable depuis le formulaire d'édition de l'application
4. Placez vos fichiers dans ~/apps/myapp/
5. Installez les dépendances avec npm install
6. Redémarrez l'application depuis l'Apanel

7. Utiliser node, npm et yarn sans créer d'application

Si vous avez seulement besoin des exécutables node et npm (pour compiler des assets, lancer un script ponctuel, installer des dépendances), il n'est pas nécessaire de créer une application via l'outil Applications.

Accès rapide via le PATH

Les binaires sont disponibles directement sur le serveur :

/opt/alt/alt-nodejs24/root/usr/bin/node
/opt/alt/alt-nodejs24/root/usr/bin/npm

Pour éviter de taper le chemin complet à chaque fois, ajoutez cette ligne dans votre ~/.bashrc :

echo 'export PATH="$PATH:/opt/alt/alt-nodejs24/root/usr/bin/"' >> ~/.bashrc
source ~/.bashrc

Vous pouvez ensuite utiliser node, npm et npx normalement.

Changer de version

Remplacez 24 par la version souhaitée (10, 12, 14, 16, 18, 20, 22 ou 24) :

# Exemple : utiliser Node.js 20
export PATH="$PATH:/opt/alt/alt-nodejs20/root/usr/bin/"

💡 Astuce : La version de npm est liée à celle de Node.js. Node.js 24 embarque npm ~10, Node.js 20 embarque npm ~9, etc.

Installer Yarn

Une fois node et npm accessibles via le PATH :

npm install -g yarn

Pour rendre yarn accessible dans toutes les sessions, ajoutez aussi au ~/.bashrc :

echo 'export PATH="$PATH:$HOME/bin"' >> ~/.bashrc
source ~/.bashrc

⚠️ Note : Si vous avez créé une application via l'Apanel, la méthode recommandée reste d'activer l'environnement virtuel (source ~/nodevenv/apps/.../bin/activate) — cela configure automatiquement le PATH et l'environnement.

8. Code minimal fonctionnel

Voici un exemple de app.js fonctionnel pour Node.js :

const http = require('http');

const server = http.createServer((req, res) => {
    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
    res.end(`<!DOCTYPE html>
<html lang="fr">
<head>
    <meta charset="UTF-8">
    <title>Node.js sur votresite.ch</title>
</head>
<body>
    <h1>Application Node.js</h1>
    <p>Hébergée sur SwissCenter via l'Apanel</p>
</body>
</html>`);
});

server.listen(process.env.PORT || 3000);

⚠️ Important : Utilisez toujours process.env.PORT || 3000 pour écouter sur le port fourni par Passenger. Ne lancez pas l'application manuellement avec node app.js — Passenger gère le cycle de vie.

9. Redémarrer l'application

Après avoir modifié le code de votre application :

1. Retournez dans Applications (Technologies web)
2. Cliquez sur le bouton Restart (🔄) à côté de votre application
3. Patientez quelques secondes — le statut revient à running

10. Accéder à l'application

Votre application est accessible à l'URL configurée :

• https://votresite.ch/myapp

11. Variables d'environnement

Vous pouvez définir des variables d'environnement dans le formulaire de création ou d'édition de l'application :

Pour ajouter des variables personnalisées, cliquez sur Ajouter une variable.

12. Erreurs courantes et dépannage

L'application ne répond pas (Passenger — "We're sorry, but something went wrong.")

Causes possibles :

1. Le fichier de démarrage est incorrect — Vérifiez que le fichier existe et contient un appel à listen()
2. Syntaxe JavaScript invalide — Vérifiez les logs via l'Explorateur de fichiers ou SSH
3. Version Node.js incompatible — Essayez de changer la version (ex: 24.19 au lieu de 20.20)
4. Port non défini — Assurez-vous d'utiliser process.env.PORT dans votre code

Mode Debug avancé

Pour activer le mode debug de Passenger, ajoutez un fichier .htaccess à la racine du domaine :

PassengerAppEnv development
PassengerFriendlyErrorPages on
PassengerAppLogFile "/home/votresite/apps/myapp/error.log"

Erreurs NPM (mémoire, compilation)

Les erreurs wasm memory, fork failed ou out of memory lors de l'installation de dépendances peuvent survenir :

• Utilisez un client SSH dédié (Putty, Terminal) plutôt que le terminal intégré de l'Apanel
• Demandez l'activation des compilateurs au support si vous voyez des erreurs gcc, make, node-gyp

13. Comment Passenger lance l'application

Phusion Passenger est le moteur d'exécution utilisé en arrière-plan. Il se charge de :

1. Lancer votre application Node.js
2. Intercepter l'appel à listen() pour utiliser une socket Unix (pas de conflit de port)
3. Relancer l'application si elle plante
4. Faire le lien entre votre application et le nom de domaine

⚠️ Ne lancez pas votre application manuellement avec node app.js ! Passenger est conçu pour gérer le cycle de vie. Si vous lancez l'application vous-même :

• Le port (ex: 3000) ne sera pas accessible depuis l'extérieur
• Impossible de faire le lien avec votre nom de domaine
• Aucune relance automatique en cas de crash

Applications non-web (bots, scripts)

Si votre application n'appelle jamais listen(), elle ne peut pas être gérée par Passenger. Utilisez l'outil Applications uniquement pour créer l'environnement virtuel, puis lancez votre script manuellement avec un mécanisme de relance (cron).

14. Déploiement via CLI (CloudLinux Selector)

Pour les déploiements automatisés (Git, CI/CD), utilisez la commande cloudlinux-selector :

# Lister les applications
cloudlinux-selector list --json --interpreter nodejs --user votresite

# Créer une application
cloudlinux-selector create --interpreter nodejs --user votresite \
    --app-root apps/myapp --app-uri /myapp \
    --version 20.20 --startup-file app.js

# Redémarrer l'application
cloudlinux-selector restart --interpreter nodejs --user votresite --app-root apps/myapp

15. Compatibilité CloudLinux

Ce guide est compatible avec les hébergements SwissCenter fonctionnant sous CloudLinux avec l'Apanel.