Comment utiliser Node.js sur un Hébergement Web Gandi¶

Prérequis
Support des versions
Fonctionnement général
Boot
Variables d’environnement
- Accès aux variables d’environnement
- Définition des variables d’environnement
Gestion des dépendances
- Sélection de la version de Node.js
- Trucs et astuces pour le déploiement
Websockets
Journaux
Base de données
- MySQL
- PostgreSQL

Hébergement Web Node.js rend facile et abordable l’hébergement d’applications Node.js évolutives.

Prérequis ¶

Node.js et NPM installés sur votre ordinateur,

Votre application doit utiliser NPM pour gérer ses dépendances.

Vous avez actuellement le choix entre les versions 10, 12, 14 et 18 de nodejs lors de la configuration de votre Hébergement Web. Il est fortement recommandé de n’utiliser que ces versions de node.js sur nos hébergements, les versions fournies par Node Version Manager (nvm) pouvant ne pas être entièrement compatible.

Si vous disposez d’une version antérieure à nodejs 18, vous pouvez toujours procéder à une mise à jour via l’administration de votre hébergement disponible dans votre compte Gandi.

Fonctionnement général ¶

Votre application Node.js doit être composée d’au moins un fichier appelé server.js, mais la configuration recommandée est d’utiliser un fichier package.json où vous spécifiez les dépendances et le point d’entrée de votre application.

Ce fichier de point d’entrée sera exécuté par l’interpréteur Node.js au démarrage de votre instance, ou après un déploiement avec git+SSH.

Pour recevoir des requêtes HTTP et HTTPS, votre application doit écouter sur un port spécifié par la variable d’environnement PORT, disponible dans Node.js avec process.env.PORT.

Un nom de domaine est mis à votre disposition lors de la création de l’instance à des fins de test. En outre, vous pouvez lier de nombreux domaines et sous-domaines à votre application Node.js.

Boot ¶

La plate-forme Hébergement Web essaie de démarrer votre application en utilisant la séquence suivante :

Utiliser un script de démarrage spécifié dans package.json.

Utiliser le point d’entrée par défaut défini dans le champ main du package.json.

Utilisez un fichier server.js, s’il existe à la racine de l’application.

Veuillez vérifier ci-dessous pour plus d’informations sur chacune de ces options.

Utilisation de package.json (recommandé)¶

La méthode standard pour démarrer une application Node.js est d’utiliser les préférences du fichier NPM package.json. Hébergement Web ne permettait pas cette méthode auparavant, mais c’est maintenant la méthode recommandée pour démarrer votre application.

Le fichier package.json doit être placé à la racine de votre projet. Il doit contenir soit une propriété package.json['main'] définissant le point d’entrée de l’application (le fichier à lancer au démarrage), soit une commande de démarrage spécifiée dans package.json['scripts']['start'].

La plupart des applications pré-empaquetées comme Ghost par exemple, utilisent déjà cette convention, les rendant plus facile à installer.

Définir un point d’entrée ¶

Vous pouvez définir un point d’entrée en utilisant le champ main. Entrez simplement le nom du fichier à partir duquel démarrer, et Hébergement Web utilisera node pour l’exécuter.

Par exemple, pour démarrer à partir du fichier index.js` :

package.json

{
  "name" : "foo",
  "version" : "1.2.3",
  "description" : "A packaged foo fooer for fooing foos",
  "main" : "index.js",
}

Exécution d’une commande personnalisée ¶

Vous pouvez également définir l’ensemble de la commande à exécuter en définissant le champ ['scripts']['start']. L’instance Hébergement Web exécutera simplement cette commande pour démarrer l’application.

L’exemple suivant est l’équivalent de l’utilisation de la technique du « point d’entrée » décrite ci-dessus.

package.json

{
  "name" : "foo",
  "version" : "1.2.3",
  "description" : "A packaged foo fooer for fooing foos",
  "scripts": {
    "start": "node index.js"
  }
}

Le script de démarrage est très flexible et fournit une variété de fonctionnalités pour personnaliser le fonctionnement de votre application. Par exemple, vous pouvez prendre en charge ES6 en fonctionnant en mode harmonie.

package.json

{
  "name" : "foo-ecma-script",
  "version" : "6",
  "description" : "ES6 sur Hébergement Web",
  "engines": {
    "node": "6"
  },
  "scripts": {
    "start": "node --harmony index.js"
  }
}

Combiné avec des variables d’environnement, vous pouvez utiliser cette fonctionnalité pour lancer votre application avec un gestionnaire de processus comme pm2 et contrôler manuellement le cycle de vie de votre processus. Ou même essayer quelques trucs amusants avec des threads et libuv.

Utilisation de server.js ¶

La façon la plus simple de démarrer une application Node.js pour Hébergement Web est de créer un fichier nommé server.js à la racine de votre projet. En l’absence de l’un des paramètres spécifiés dans la section précédente, l’instance tentera de démarrer votre application en exécutant ce fichier.

Variables d’environnement ¶

Votre application peut s’appuyer sur des variables d’environnement pour un certain nombre d’options de configuration, définies par la plate-forme ou par vous-même au moment du lancement.

Voici quelques exemples de variables d’environnement définies par la plate-forme avant le démarrage de votre application :

PORT=8080
NODE_ENV=production
WEB_MEMORY=128
WEB_CONCURRENCY=2

Note

Les valeurs WEB_MEMORY et WEB_CONCURRENCY dépendent du type d’instance (S, M, L, XL, XXL). Le premier est toujours fixé au maximum pour votre type d’instance. Cette dernière est notre recommandation basée sur la taille de l’instance, mais vous pouvez l’adapter à vos besoins.

Accès aux variables d’environnement ¶

Vous pouvez récupérer les variables d’environnement de votre application de la manière habituelle, en accédant à process.env. Par exemple :

var port = process.env.PORT;
console.log(process.env.PORT);
// => 8080

Définition des variables d’environnement ¶

Vous pouvez définir ou écraser des variables d’environnement à partir de votre application ou au démarrage à l’aide du script de démarrage.

À partir de l’application, vous pouvez simplement définir la valeur d’une variable d’environnement avec process.env. Par exemple :

process.env.NODE_ENV = "staging";
console.log(process.env.NODE_ENV); // => "staging"

Au démarrage, utilisez package.json['scripts']['start'] pour définir une ou plusieurs variables d’environnement dans le style shell. Par exemple :

package.json

{
...
  "scripts": {
    "start": "NODE_ENV=staging node index"
  }
}

Assurez-vous de ne pas surcharger la variable d’environnement PORT, car votre application pourrait ne pas être accessible par la suite. En général, assurez-vous de ne pas surcharger un paramètre important avant de lancer votre application avec une commande personnalisée.

Gestion des dépendances ¶

La plate-forme Node.js Hébergement Web s’occupe de l’installation de vos dépendances et du lancement de votre application pendant le processus de déploiement git+SSH. Spécifiez simplement les dépendances dans le fichier package.json à la racine de votre projet :

package.json

{
  "name": "website",
  "version": "0.0.1",
  "dependencies": {
    "express": "3.x"
  }
}

Sélection de la version de Node.js ¶

Spécifiez simplement les versions que vous voulez utiliser dans le fichier package.json de votre projet. Par exemple :

package.json

{
  "engines": {
    "node": "14",
    "npm": "*"
  }
}

L’exemple ci-dessus forcera l’utilisation de Node.js 6.x. Pour plus d’informations sur le champ engines, voir https://docs.npmjs.com/files/package.json#engines.

Visitez le site officiel de Node.js pour plus d’informations sur les versions actuelles.

Trucs et astuces pour le déploiement ¶

Le script npm postinstall peut-être utilisé pour déployer l’application dans l’environnement de déploiement de l’instance Hébergement Web dès la fin de l’étape npm install. Vous pourrez débuter la commande postinstall par [ -z \"$GANDI\" ] || NODE_ENV=production pour assurer que la commande est exécutée uniquement dans l’environnement de déploiement de l’instance Hébergement Web et non dans l’environnement de développement local.

Note

La valeur de la variable d’environnement de l’instance $GANDI est définie avec le nom d’hôte de l’instance. Vous pouvez utiliser cette valeur si vous disposez de plusieurs instance, pour la pre-production, la production.

package.json

{
  "scripts": {
    "postinstall": "[ -z \"$GANDI\" ] || NODE_ENV=production npm run build"
  }
}

Vous pouvez également définir package.json[config] pour assurer que le déploiement utilise NODE_ENV=development. À utiliser par exemple pour installer dependencies + devDependencies durant le processus de déploiement. À ne pas utiliser en revanche si vous souhaitez installer uniquement les dependencies avant de démarrer l’application.

package.json

{
  "config": {
    "NODE_ENV": "development"
  }
}

Websockets ¶

Websockets n’est actuellement pas pris en charge sur l’Hébergement Web Gandi.

Journaux ¶

La sortie standard et les erreurs de votre site internet sont envoyées à un fichier journal sur votre disque, auquel vous pouvez accéder pour déboguer votre application.

via la console SSH : /srv/data/var/log/www/nodejs.log

via SFTP : /lamp0/var/log/www/nodejs.log.

Ce fichier journal contient également la sortie du programme NPM qui est en charge des dépendances de votre application.

De plus, vous pouvez consulter l’historique des actions entreprises par le programme chargé de lancer votre application :

via la console SSH : /srv/data/var/log/www/nodejs-watchd.log.

via SFTP : /lamp0/var/log/www/nodejs-watchd.log.

Vous pouvez également voir si votre application Node.js a démarré correctement dans ce fichier.

Base de données ¶

MySQL ¶

MySQL est disponible pour une utilisation avec les instances Node.js sur un Hébergement Web Gandi.

Vous pouvez vous connecter au service de base de données MySQL via son socket Unix, disponible sur /srv/run/mysqld/mysqld/mysqld.sock. L’utilisateur par défaut est root et aucun mot de passe n’est requit par défaut. Cependant, vous devez créer des informations d’identification sûres pour une utilisation dans le monde réel. Vous pouvez également utiliser la base de données default_db pour des réglages rapides et des tests, car elle est automatiquement configurée lors de la création de l’instance.

Vous pouvez créer autant de bases de données et d’utilisateurs de bases de données que vous le souhaitez ; vous n’êtes limité que par votre espace disque, que vous pouvez augmenter à tout moment jusqu’à 1 To.

Vous pouvez gérer votre base de données MySQL avec les outils shell standard (mysql, mysqldump, etc.) via la console SSH, ou depuis la console d’administration web avec PHPMyAdmin. Consultez l’article de référence sur la gestion de MySQL sur Hébergement Web pour en savoir plus.

Ci-dessous se trouve un exemple de code minimaliste Node.js pour tester la connexion à la base de données sur Hébergement Web :

index.js

var http = require('http'),
    mysql = require('mysql');

var mysql_conn = mysql.createConnection({
  socketPath: '/srv/run/mysqld/mysqld.sock',
  database: 'default_db',
  user: 'root',
  password: ''
});

var test_mysql_conn = function(callback) {
  mysql_conn.connect(function(err) {
    if (err) {
      console.log(err.code);
      if (callback) callback("NOT WORKING");
    } else {
      console.log('connected...');
      if (callback) callback("OK");
    }
  });
  mysql_conn.end();
};

http.createServer(function (req, res) {
  res.writeHead(200, {'Content-Type': 'text/plain'});
  res.write('Hello Node.js!\n');
  test_mysql_conn(function(mysql_status) {
    res.write('MySQL connection: ' + mysql_status + '\n');
    res.end();
  });
}).listen(process.env.PORT);

package.json

{
  "name": "sample-nodejs-mysql-app",
  "version": "1.0.0",
  "description": "Sample Node.js MySQL app pour Hébergement Web",
  "main": "index.js",
  "engines": {
    "node": "4"
  },
  "dependencies": {
    "mysql": "*"
  }
}

PostgreSQL ¶

PostgreSQL est disponible pour Hébergement Web avec Node.js.

Le service PostgreSQL de votre instance sera accessible sur localhost au port 5432.

Par défaut, vous pouvez utiliser l’utilisateur hosting-db` sans mot de passe pour vous connecter à la base de données par défaut, appelée postgres. Nous vous recommandons de créer des informations d’identification sécurisées pour une utilisation dans le monde réel.

Vous pouvez créer autant d’utilisateurs et de bases de données que vous le souhaitez ; vous n’êtes limité que par votre espace disque, que vous pouvez augmenter à tout moment jusqu’à 1 To.

Vous pouvez gérer votre base de données PostgreSQL avec les commandes shell standard via la console SSH (psql, pg_dump, etc.), ou depuis le panneau d’administration Web avec phpPgAdmin. Consultez l’article de référence sur la gestion de PostgreSQL sur Hébergement Web pour en savoir plus.

Ci-dessous se trouve un exemple de code minimaliste Node.js pour tester la connexion à la base de données sur Hébergement Web :

index.js

var http = require('http'),
    pg = require('pg');

var pg_url = "tcp://hosting-db@localhost/postgres";
var pg_conn = new pg.Client(pg_url);

var test_pg_conn = function(callback) {
  pg_conn.connect(function(err) {
    if (err) {
      console.log(err);
      if (callback) callback("NOT WORKING");
    } else {
      console.log('Connected to PostgreSQL');
      if (callback) callback("OK");
    }
  });
};

http.createServer(function (req, res) {
  res.writeHead(200, {'Content-Type': 'text/plain'});
  res.write('Hello Node.js!\n');
  test_pg_conn(function(pg_status) {
    res.write('PostgreSQL connection: ' + pg_status + '\n');
    res.end();
  });
}).listen(process.env.PORT);

package.json

{
  "name": "sample-nodejs-pgsql-app",
  "version": "1.0.0",
  "description": "Sample Node.js PostgreSQL app pour Hébergement Web",
  "main": "index.js",
  "engines": {
    "node": "4"
  },
  "dependencies": {
    "pg": "*"
  }
}