Node.js: Premiers pas

Découvrez comment déployer rapidement et en toute sécurité un service Node.js sur Stackhero

👋 Bienvenue sur la documentation de Stackhero !

Stackhero propose une solution Node.js cloud prête à l'emploi qui offre de nombreux avantages, notamment :

Déployez votre application en quelques secondes avec un simple git push.

Utilisez votre propre nom de domaine et bénéficiez de la configuration automatique des certificats HTTPS pour une sécurité renforcée.

Profitez de la tranquillité d'esprit avec des sauvegardes automatiques, des mises à jour en un clic, et une tarification simple, transparente et prévisible.

Obtenez des performances optimales et une sécurité robuste grâce à une VM privée et dédiée.

Gagnez du temps et simplifiez-vous la vie : il ne faut que 5 minutes pour essayer la solution d'hébergement cloud Node.js de Stackhero !

Déployer votre service Node.js sur Stackhero est conçu pour être rapide, efficace et fiable. Dans ce guide, nous allons parcourir les étapes essentielles pour mettre votre application en ligne en quelques minutes, tout en assurant sécurité et performance.

Démarrer un service Node.js

Pour commencer, créons un service Node.js sur Stackhero. Cela constituera la base du déploiement de votre application et vous donnera accès à tous les avantages de l'hébergement cloud Stackhero.

Prérequis

Avant de commencer, assurez-vous de disposer des outils suivants :

Git : Téléchargez-le sur https://git-scm.com/downloads.
Utilisateurs Windows : Pour une expérience optimale, il est conseillé d'utiliser Windows Terminal, disponible sur le Microsoft Store.

Configurer votre service

L'étape principale de configuration consiste à mettre à jour votre clé publique SSH. Cette clé permet à Stackhero d'accéder de façon sécurisée à votre dépôt de code.

Pour retrouver votre clé publique, exécutez l'une de ces commandes dans votre terminal :

cat ~/.ssh/id_rsa.pub

cat ~/.ssh/id_ed25519.pub

Si vous ne possédez pas encore de paire de clés SSH, vous pouvez en générer une avec ssh-keygen sur Linux ou macOS, ou ssh-keygen.exe sur Windows.

Une fois votre clé publique obtenue, connectez-vous au tableau de bord Stackhero, sélectionnez votre service Node.js, accédez à la section de configuration et collez votre clé dans le champ prévu à cet effet.

Tip: Si vous souhaitez que votre clé publique SSH soit disponible pour tous vos futurs services, vous pouvez la définir globalement. Rendez-vous simplement sur le tableau de bord Stackhero, cliquez sur votre photo de profil (en haut à droite), allez dans "Votre profil" et collez votre clé publique SSH à cet endroit.

Cloner l'exemple

Pour faciliter vos premiers pas, nous mettons à disposition une application Node.js exemple qui montre comment fonctionne le déploiement sur Stackhero. Vous pouvez cloner le dépôt avec ces commandes :

git clone https://github.com/stackhero-io/nodejsGettingStarted.git stackhero-nodejs-getting-started
cd stackhero-nodejs-getting-started

Configurer le dépôt distant

Déployer votre application via Git sur Stackhero est simple. Sur la page principale de votre service, vous trouverez une commande pour ajouter un dépôt distant Git, qui ressemble à ceci :

git remote add stackhero ssh://stackhero@<XXXXXX>.stackhero-network.com:222/project.git

Copiez et collez cette commande dans votre terminal pour configurer le dépôt distant.

Déployer votre application Node.js

Pour déployer, il suffit de pousser votre code vers Stackhero avec :

git push stackhero main

Lors du premier push, il vous sera demandé de confirmer l'empreinte de la clé. Tapez simplement "yes" pour continuer.

En quelques instants, votre application sera en ligne. Vous pouvez vérifier son statut en visitant l'URL affichée sur votre tableau de bord Stackhero (par exemple, https://<XXXXXX>.stackhero-network.com).

C'est tout, votre application est maintenant déployée.

Si vous souhaitez apporter des modifications, mettez simplement à jour votre fichier app.js, validez et poussez vos changements :

git add -A .
git commit -m "Update app.js"
git push stackhero main

Déployer une application existante

Si vous avez déjà une application Node.js, vous pouvez ajouter le dépôt distant Stackhero comme indiqué ci-dessus et déployer votre code avec :

git push stackhero main

Gérer l'erreur "failed to push some refs to '[...]'"

Si vous rencontrez cette erreur :

error: failed to push some refs to '[...]'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
(e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

Cela signifie que votre dépôt local n'est pas synchronisé avec le dépôt distant. Vous pouvez forcer le push avec :

git push -f stackhero main

Gérer l'erreur "src refspec main does not match any"

Si vous voyez ce message lors du push :

error: src refspec main does not match any
error: failed to push some refs to 'ssh://<XXXXXX>.stackhero-network.com:222/project.git'

Cela signifie généralement que la branche main n'existe pas. Essayez alors de pousser la branche master à la place :

git push stackhero master

Gérer l'erreur "Everything up-to-date" lors du push

Si Git vous indique "Everything up-to-date" mais que vos modifications ne sont pas déployées, il se peut que vous ayez oublié de valider vos changements. Essayez la commande suivante :

git add -A .
git commit -m "Votre message de commit"
git push stackhero main

Si vous n'avez pas de modifications mais souhaitez tout de même déclencher un déploiement, vous pouvez forcer un commit vide :

git commit --allow-empty -m "Force update"
git push stackhero main

Déployer une branche autre que main

Si vous souhaitez déployer une branche différente de main, comme production, vous pouvez utiliser :

git push stackhero production:main

Déployer un tag

Si vous utilisez des tags et souhaitez déployer un tag spécifique (par exemple, v1.0), exécutez :

git push stackhero 'v1.0^{}:main'

Le ^{} permet de pousser le commit associé au tag.

Revenir en arrière ou déployer un commit spécifique

Pour déployer un commit précis, commencez par retrouver son hash avec git log. Puis déployez-le avec :

git push -f stackhero <HASH>:main

Déployer sur plusieurs environnements

Vous pouvez souhaiter séparer vos environnements de production et de staging. Pour renommer le dépôt distant actuel de stackhero en stackhero-staging, exécutez :

git remote rename stackhero stackhero-staging

Ensuite, créez un nouveau service Node.js dans votre tableau de bord Stackhero et ajoutez-le comme stackhero-production :

git remote add stackhero-production ssh://stackhero@<XXXXXX>.stackhero-network.com:222/project.git

Vous pouvez alors déployer sur chaque environnement avec :

git push stackhero-production main

git push stackhero-staging main

Enregistrer le mot de passe de votre clé privée SSH dans le trousseau macOS

Sur macOS, il se peut que votre mot de passe SSH soit demandé à chaque push. Pour plus de confort et de sécurité, vous pouvez l'enregistrer dans le trousseau macOS avec :

/usr/bin/ssh-add --apple-use-keychain ~/.ssh/id_rsa

Cette commande enregistre le mot de passe de votre clé afin que vous ne soyez plus sollicité lors des prochains déploiements.

Gérer les secrets

Lorsque vous travaillez avec des environnements de staging et de production, il est essentiel de gérer les secrets comme les tokens ou mots de passe de façon sécurisée. Plutôt que de stocker ces secrets dans votre dépôt, utilisez des variables d'environnement pour plus de sécurité.

Vous pouvez ajouter des variables d'environnement dans le tableau de bord Stackhero et y accéder dans votre code Node.js. Par exemple, si vous définissez une variable nommée mySecret, vous pouvez y accéder ainsi dans votre application :

process.env.mySecret

Ouvrir d'autres ports réseau

Si votre application doit utiliser d'autres protocoles que HTTP, vous pouvez ouvrir des ports TCP ou UDP supplémentaires. Cela se fait directement dans le tableau de bord Stackhero en précisant le port d'entrée public, le port de destination sur votre service Node.js et le protocole (TCP ou UDP).

Stocker des fichiers

Pour stocker des fichiers utilisateurs, comme des photos, il est recommandé d'utiliser une solution d'object storage. Cela vous permet de partager les fichiers entre plusieurs services et instances, et de séparer votre code de vos données. Nous recommandons MinIO comme solution rapide, simple et puissante, compatible avec le protocole Amazon S3.

Si vous préférez un stockage local, vous pouvez utiliser le stockage persistant disponible avec votre instance Node.js. Ce stockage se trouve dans le dossier /persistent/storage/.

ATTENTION : Stockez toujours vos données dans le dossier /persistent/storage/.

Les données placées en dehors de ce dossier peuvent être perdues en cas de redémarrage de l'instance ou lors d'un push de code.

Arrêt en douceur (graceful shutdown)

Lors du déploiement d'une nouvelle version de votre application, la version précédente reçoit un signal de terminaison avant l'arrêt. Cela permet à votre application de fermer proprement les connexions à la base de données et d'arrêter les autres services.

Le signal de terminaison SIGTERM est envoyé à votre application. Vous pouvez le gérer dans votre code comme ceci :

process.on('SIGTERM', () => {
  // Ce log apparaît sur le tableau de bord Stackhero dans l'onglet "logs"
  console.info('SIGTERM signal received.');

  // Fermez ici les connexions à la base de données ou autres services
  // ...
});

Utiliser plusieurs cœurs CPU

Par défaut, Node.js utilise un seul cœur et un seul thread. Pour exploiter tous les cœurs CPU disponibles, vous pouvez utiliser l'API cluster de Node.js. La documentation officielle est disponible ici : https://nodejs.org/api/cluster.html.

Voici un exemple simple qui crée un serveur HTTP utilisant tous les CPUs disponibles :

const cluster = require('cluster');
const http = require('http');
const cpusCount = require('os').cpus().length;

if (cluster.isMaster) {
  console.log(`Master ${process.pid} is running`);

  // Fork workers
  for (let i = 0; i < cpusCount; i++) {
    cluster.fork();
  }

  cluster.on('exit', (worker, code, signal) => {
    console.log(`Worker ${worker.process.pid} died`);
  });
} else {
  // Les workers partagent toute connexion TCP, ici un serveur HTTP
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end('hello world\n');
  }).listen(8000);

  console.log(`Worker ${process.pid} started`);
}