Pas encore de site web à héberger ? Nous créons aussi votre site ou votre application. Voir les packs

KENN HOSTING
Tous les articles
Tutoriels

Déployer une API Node.js/Express sur cPanel

Aurel KENNE15 octobre 20267 min de lecture

Avant de commencer

Une API Node.js/Express n'est pas un simple fichier statique à copier dans public_html : c'est un processus qui doit tourner en continu sur le serveur, écouter un port, et redémarrer si besoin. cPanel gère ça nativement grâce à un outil intégré, Setup Node.js App (aussi appelé "Node.js Selector" selon les versions du thème), qui s'appuie sur Passenger pour faire tourner votre application sans que vous ayez à gérer vous-même un service système.

Ce guide suppose que vous avez déjà :

  • Un hébergement cPanel actif chez KennHosting
  • Le code de votre API Express prêt (en local ou dans un dépôt Git)
  • Un fichier package.json à la racine de votre projet

Étape 1 : créer l'application dans cPanel

Connectez-vous à votre cPanel, puis dans la section Logiciels, cliquez sur Setup Node.js App.

Cliquez ensuite sur Create Application. Le formulaire vous demande plusieurs informations :

  • Node.js version : choisissez une version récente proposée dans la liste (une version LTS comme 18 ou 20 est un bon choix par défaut).
  • Application mode : sélectionnez Production.
  • Application root : le dossier qui contiendra le code de votre API, par exemple monapi. Ce dossier se trouve sous le répertoire personnel de votre compte, pas directement dans public_html.
  • Application URL : le domaine, sous-domaine, ou sous-dossier public par lequel votre API sera accessible (par exemple api.votredomaine.com).
  • Application startup file : le fichier qui démarre votre serveur Express, généralement server.js ou app.js selon votre projet.

Validez avec Create.

Étape 2 : récupérer la commande d'activation de l'environnement

Une fois l'application créée, cPanel affiche en haut de la page une commande d'activation, du type :

source /home/votrecompte/nodevenv/monapi/18/bin/activate && cd /home/votrecompte/monapi

Cette commande est propre à votre compte et à l'application que vous venez de créer (le chemin change selon votre nom d'utilisateur, le nom du dossier et la version de Node choisie). Copiez-la exactement telle qu'affichée dans votre interface, ne la recopiez pas depuis cet article : les chemins ne correspondront pas.

Elle active un environnement virtuel Node.js dédié à cette application, isolé des autres apps que vous pourriez créer sur le même compte.

Étape 3 : déposer le code de votre API

Vous avez deux façons de mettre votre code dans le dossier Application root défini à l'étape 1 :

Option A : Gestionnaire de fichiers ou FTP

Compressez votre projet en .zip en local (sans le dossier node_modules, il sera réinstallé côté serveur), uploadez-le dans le dossier de l'application via le Gestionnaire de fichiers de cPanel, puis extrayez l'archive sur place.

Option B : Git, si vous êtes à l'aise en ligne de commande

Ouvrez le Terminal depuis cPanel (ou connectez-vous en SSH), placez-vous dans le dossier de l'application et clonez votre dépôt :

cd /home/votrecompte/monapi
git clone https://github.com/votre-compte/votre-depot.git .

Le point final (.) clone le contenu du dépôt directement dans le dossier courant, sans créer de sous-dossier supplémentaire.

Étape 4 : installer les dépendances

Deux méthodes, au choix :

Depuis le Terminal

Activez l'environnement avec la commande récupérée à l'étape 2, puis lancez l'installation :

source /home/votrecompte/nodevenv/monapi/18/bin/activate && cd /home/votrecompte/monapi
npm install

Depuis l'interface Setup Node.js App

Retournez sur la page de votre application dans cPanel et cliquez sur le bouton Run NPM Install. cPanel exécute l'installation pour vous, dans le bon environnement, sans que vous ayez besoin du Terminal.

Les deux méthodes donnent le même résultat : utilisez celle qui vous est la plus confortable.

Étape 5 : configurer les variables d'environnement

Contrairement à un déploiement classique avec un fichier .env, Setup Node.js App gère les variables d'environnement directement dans son interface, dans la section Environment Variables. Passenger les injecte lui-même dans le processus au démarrage.

Ajoutez-y les informations nécessaires à votre application, par exemple :

DB_HOST=localhost
DB_USER=votrecompte_dbuser
DB_PASSWORD=votre_mot_de_passe
DB_NAME=votrecompte_nomdebase
PORT=3000

Dans votre code Express, vous les lisez normalement via process.env :

const dbHost = process.env.DB_HOST;
const dbUser = process.env.DB_USER;
const port = process.env.PORT || 3000;

Après tout ajout ou modification de variable, pensez à redémarrer l'application (étape 7) pour que le changement soit pris en compte.

Étape 6 : connecter votre API à une base MySQL

Si votre API a besoin d'une base de données, elle doit être créée au préalable depuis cPanel (MySQL Databases), avec un utilisateur disposant des privilèges sur cette base. Si ce n'est pas encore fait, consultez notre article dédié à la création d'une base de données dans cPanel : la procédure est la même, qu'elle serve à un site classique ou à une API Node.js.

Une fois la base créée, renseignez ses identifiants dans les variables d'environnement de l'étape précédente, puis connectez-vous depuis votre code avec le client MySQL de votre choix (mysql2, sequelize, knex, etc.) :

npm install mysql2
const mysql = require('mysql2/promise');

const connection = await mysql.createConnection({
    host: process.env.DB_HOST,
    user: process.env.DB_USER,
    password: process.env.DB_PASSWORD,
    database: process.env.DB_NAME,
});

Étape 7 : démarrer ou redémarrer l'application

Retournez sur la page Setup Node.js App, repérez votre application dans la liste, et cliquez sur Restart. C'est cette action qui démarre réellement votre processus Express et le rend accessible à l'URL que vous avez configurée à l'étape 1.

Vous devrez répéter ce clic sur Restart à chaque fois que vous modifiez le code, installez une nouvelle dépendance, ou changez une variable d'environnement : Passenger ne recharge pas automatiquement votre application à chaud.

Étape 8 : vérifier que l'API répond

Ouvrez l'URL configurée à l'étape 1 dans votre navigateur, ou testez une route avec curl :

curl https://api.votredomaine.com/

Si votre application répond, le déploiement est terminé. Si vous obtenez une erreur, retournez sur la page Setup Node.js App : un lien vers les journaux d'erreur (Error log) y est disponible pour identifier ce qui bloque, le plus souvent une variable d'environnement manquante ou une dépendance non installée.

Mettre à jour votre API après un changement de code

Il est important de le savoir avant de choisir cette méthode : contrairement à une plateforme de déploiement automatique connectée à GitHub, Setup Node.js App ne redéploie pas automatiquement votre application à chaque push. Il n'y a pas de webhook intégré qui déclenche une mise à jour toute seule.

À chaque nouvelle version de votre code, vous devrez :

  1. Mettre à jour les fichiers sur le serveur (nouveau git pull si vous avez cloné votre dépôt, ou nouvel upload via le Gestionnaire de fichiers).
  2. Relancer npm install si de nouvelles dépendances ont été ajoutées.
  3. Cliquer sur Restart depuis l'interface Setup Node.js App.

Si vous travaillez avec Git, le git pull peut se faire directement depuis le Terminal cPanel :

source /home/votrecompte/nodevenv/monapi/18/bin/activate && cd /home/votrecompte/monapi
git pull
npm install

Puis un clic sur Restart pour appliquer les changements.

En résumé

Setup Node.js App vous donne un contrôle total sur votre API Express : version de Node, variables d'environnement, redémarrage à la demande, tout se pilote depuis cPanel ou le Terminal. La contrepartie de ce contrôle, c'est que chaque mise à jour se déclenche manuellement, étape par étape, plutôt qu'automatiquement à chaque push Git. C'est un vrai avantage si vous voulez garder la main sur le moment exact où une nouvelle version part en production.