Configurer une application Node.js pour Azure App Service

Article
06/01/2023

Les applications Node.js doivent être déployées avec toutes les dépendances NPM nécessaires. Le moteur de déploiement App Service exécute automatiquement npm install --production quand vous déployez un npm install --production ou un package Zip pour lequel l’automatisation des builds est activée. Si vous déployez vos fichiers à l’aide de FTP/S, vous devez cependant télécharger les packages requis manuellement.

Ce guide fournit les concepts et instructions clés aux développeurs Node.js qui déploient des applications sur App Service. Si vous n’avez jamais utilisé Azure App Service, suivez le démarrage rapide Node.js et le tutoriel Node.js avec MongoDB au préalable.

Afficher la version de Node.js

Pour afficher la version actuelle de Node.js, exécutez la commande suivante dans Cloud Shell :

az webapp config appsettings list --name <app-name> --resource-group <resource-group-name> --query "[?name=='WEBSITE_NODE_DEFAULT_VERSION'].value"

Pour afficher toutes les versions de Node.js prises en charge, accédez à https://<sitename>.scm.azurewebsites.net/api/diagnostics/runtime ou exécutez la commande suivante dans https://<sitename>.scm.azurewebsites.net/api/diagnostics/runtime :

az webapp list-runtimes --os windows | grep NODE

Pour afficher la version actuelle de Node.js, exécutez la commande suivante dans Cloud Shell :

az webapp config show --resource-group <resource-group-name> --name <app-name> --query linuxFxVersion

Pour afficher toutes les versions de Node.js prises en charge, exécutez la commande suivante dans Cloud Shell :

az webapp list-runtimes --os linux | grep NODE

Définir la version de Node.js

Pour définir votre application dans une version de Node.js prise en charge, exécutez la commande suivante dans Cloud Shell pour définir WEBSITE_NODE_DEFAULT_VERSION sur une version prise en charge :

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings WEBSITE_NODE_DEFAULT_VERSION="~16"

Remarque

Cet exemple utilise la « syntaxe avec tilde » recommandée pour cibler la dernière version disponible du runtime Node.js 16 sur App Service.

Étant donné que le runtime est régulièrement corrigé et mis à jour par la plateforme, il est déconseillé de cibler une version ou un correctif logiciel mineurs spécifiques, car leur disponibilité n’est pas garantie en raison des risques de sécurité potentiels.

Notes

Vous devez définir la version de Node.js dans le fichier package.json de votre projet. Le moteur de déploiement s’exécute dans un processus distinct qui inclut toutes les versions de Node.js prises en charge.

Pour définir votre application dans une version de Node.js prise en charge, exécutez la commande suivante dans Cloud Shell :

az webapp config set --resource-group <resource-group-name> --name <app-name> --linux-fx-version "NODE|14-lts"

Ce paramètre spécifie la version de Node.js à utiliser, à la fois lors de l’exécution et pendant la restauration de package automatisée dans Kudu.

Notes

Vous devez définir la version de Node.js dans le fichier package.json de votre projet. Le moteur de déploiement s’exécute dans un conteneur distinct qui inclut toutes les versions de Node.js prises en charge.

Obtenir le numéro de port

Votre application Node.js doit écouter sur le port approprié pour recevoir les demandes entrantes.

Dans App Service sur Windows, les applications Node.js sont hébergées avec IISNode, et votre application Node.js doit écouter sur le port spécifié dans la variable process.env.PORT. L’exemple suivant montre comment le faire dans une application Express simple :

App Service définit la variable d’environnement PORT dans le conteneur Node.js et transfère les demandes entrantes à votre conteneur sur ce numéro de port. Pour recevoir les demandes, votre application doit écouter sur ce port en utilisant process.env.PORT. L’exemple suivant montre comment le faire dans une application Express simple :

const express = require('express')
const app = express()
const port = process.env.PORT || 3000

app.get('/', (req, res) => {
  res.send('Hello World!')
})

app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`)
})

Personnaliser l’automatisation de la génération

Si vous déployez votre application à l’aide de packages Git ou zip avec activation de l’automatisation de la génération, ce processus d’automatisation d’App Service exécute pas à pas la séquence suivante :

Exécution du script personnalisé s’il est spécifié par PRE_BUILD_SCRIPT_PATH.
Exécution de npm install sans aucun indicateur, qui comprend les scripts npm preinstall et postinstall, et installe également devDependencies.
Exécution de npm run build si un script de génération est défini dans votre npm run build.
Exécution de npm run build:azure si un script build:azure est défini dans votre npm run build:azure.
Exécution du script personnalisé s’il est spécifié par POST_BUILD_SCRIPT_PATH.

Remarque

Comme cela est décrit dans la documentation npm, les scripts nommés prebuild et postbuild s’exécutent avant et après build, respectivement, s’ils sont définis. preinstall et postinstall s’exécutent avant et après install, respectivement.

PRE_BUILD_COMMAND et POST_BUILD_COMMAND sont des variables d’environnement qui sont vides par défaut. Pour exécuter des commandes pré-build, définissez PRE_BUILD_COMMAND. Pour exécuter des commandes post-build, définissez POST_BUILD_COMMAND.

L’exemple suivant définit les deux variables sur une série de commandes, séparées par des virgules.

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings PRE_BUILD_COMMAND="echo foo, scripts/prebuild.sh"
az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings POST_BUILD_COMMAND="echo foo, scripts/postbuild.sh"

Pour connaître les autres variables d’environnement permettant de personnaliser l’automatisation de la génération, consultez Configuration d’Oryx.

Pour plus d’informations sur la façon dont App Service exécute et génère des applications Node.js dans Linux, consultez Documentation Oryx : Comment les applications Node.js sont détectées et générées.

Configurer un serveur Node.js

Les conteneurs Node.js sont fournis avec PM2, un gestionnaire de processus de production. Vous pouvez configurer votre application pour qu’elle démarre avec PM2, NPM ou une commande personnalisée.

Outil	Objectif
Exécuter avec PM2	Recommandé - Utilisation en production ou préproduction. PM2 fournit une plateforme complète de gestion des applications.
Exécuter npm start	À utiliser uniquement dans un environnement de développement.
Exécuter une commande personnalisée	À utiliser dans un environnement de développement intermédiaire.

Exécuter avec PM2

Le conteneur démarre automatiquement votre application avec PM2 lorsqu’un des fichiers Node.js communs se trouve dans votre projet :

bin/www
server.js
app.js
index.js
hostingstart.js
Un des fichiers PM2 suivants : process.json et ecosystem.config.js

Vous pouvez également configurer un fichier de démarrage personnalisé avec les extensions suivantes :

Fichier .js
Fichier PM2 avec l’extension .json, .config.js, .yaml ou .yml

Notes

À partir de Node 14 LTS, le conteneur ne démarre pas automatiquement votre application avec PM2. Pour démarrer votre application avec PM2, définissez la commande de démarrage sur pm2 start <.js-file-or-PM2-file> --no-daemon. Utilisez l’argument --no-daemon, car PM2 doit s’exécuter au premier plan pour que le conteneur fonctionne correctement.

Pour ajouter un fichier de démarrage personnalisé, exécutez la commande suivante dans Cloud Shell :

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "<filename-with-extension>"

Exécuter une commande personnalisée

App Service peut démarrer votre application à l’aide d’une commande personnalisée, par exemple un exécutable tel que run.sh. Par exemple, pour exécuter npm run start:prod, exécutez la commande suivante dans Cloud Shell :

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "npm run start:prod"

Exécuter npm start

Pour démarrer votre application en utilisant npm start, assurez-vous qu’un script start se trouve dans le fichier npm start. Par exemple :

{
  ...
  "scripts": {
    "start": "gulp",
    ...
  },
  ...
}

Pour utiliser un fichier package.json personnalisé dans votre projet, exécutez la commande suivante dans Cloud Shell :

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "<filename>.json"

Déboguer à distance

Notes

Le débogage à distance est actuellement en préversion.

Vous pouvez déboguer votre application Node.js à distance dans Visual Studio Code si vous la configurez pour qu’elle s’exécute avec PM2, sauf lorsque vous l’exécutez à l’aide d’un fichier .config.js, .yml ou .yaml.

Dans la plupart des cas, aucune configuration supplémentaire n’est nécessaire pour votre application. Si votre application est exécutée avec un fichier process.json (par défaut ou personnalisé), elle doit avoir une propriété script dans la racine JSON. Par exemple :

{
  "name"        : "worker",
  "script"      : "./index.js",
  ...
}

Pour configurer Visual Studio Code pour le débogage à distance, installez l’extension App Service. Suivez les instructions sur la page d’extension et connectez-vous à Azure dans Visual Studio Code.

Dans l’Explorateur Azure, recherchez l’application que vous souhaitez déboguer, cliquez dessus avec le bouton droit et sélectionnez Start Remote Debugging (Démarrer le débogage à distance). Cliquez sur Oui afin de l’activer pour votre application. App Service démarre un proxy de tunnel pour vous et joint le débogueur. Vous pouvez ensuite effectuer des requêtes auprès de l’application et voir les interruptions du débogueur au niveau des points d’arrêt.

Une fois que vous avez fini le débogage, arrêtez le débogueur en sélectionnant Déconnexion. Lorsque vous y êtes invité, vous devez cliquer sur Oui pour désactiver le débogage à distance. Pour le désactiver ultérieurement, cliquez une nouvelle fois sur votre application dans l’Explorateur Azure, puis sélectionnez Désactiver le débogage à distance.

Accéder aux variables d’environnement

Dans App Service, vous pouvez définir les paramètres de l’application en dehors de votre code d’application. Vous pouvez ensuite y accéder à l’aide du modèle Node.js standard. Par exemple, pour accéder à un paramètre d’application nommé NODE_ENV, utilisez le code suivant :

process.env.NODE_ENV

Exécuter Grunt/Bower/Gulp

Par défaut, l’automatisation de la génération App Service exécute npm install --production lorsqu’elle reconnaît qu’une application Node.js est déployée via Git ou un déploiement Zip npm install --production. Si votre application requiert des outils d’automatisation populaires, tels que Grunt, Bower ou Gulp, vous devez fournir un script de déploiement personnalisé pour l’exécution.

Pour permettre à votre dépôt d’exécuter ces outils, vous devez les ajouter aux dépendances dans package.json. Exemple :

"dependencies": {
  "bower": "^1.7.9",
  "grunt": "^1.0.1",
  "gulp": "^3.9.1",
  ...
}

Dans une fenêtre de terminal locale, remplacez le répertoire par la racine du référentiel et exécutez les commandes suivantes :

npm install kuduscript -g
kuduscript --node --scriptType bash --suppressPrompt

La racine du référentiel comporte désormais deux fichiers supplémentaires : .deployment et deploy.sh.

Ouvrez deploy.sh et recherchez la section Deployment, qui ressemble à ce qui suit :

##################################################################################################################################
# Deployment
# ----------

Cette section se termine par l’exécution de npm install --production. Ajoutez la section de code dont vous avez besoin pour exécuter l’outil requis à la fin de la section Deployment :

Bower
Gulp
Grunt

Consultez un exemple dans l’échantillon MEAN.js, où le script de déploiement exécute également une commande npm install personnalisée.

Bower

Cet extrait de code exécute bower install.

if [ -e "$DEPLOYMENT_TARGET/bower.json" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/bower install
  exitWithMessageOnError "bower failed"
  cd - > /dev/null
fi

Gulp

Cet extrait de code exécute gulp imagemin.

if [ -e "$DEPLOYMENT_TARGET/gulpfile.js" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/gulp imagemin
  exitWithMessageOnError "gulp failed"
  cd - > /dev/null
fi

Grunt

Cet extrait de code exécute grunt.

if [ -e "$DEPLOYMENT_TARGET/Gruntfile.js" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/grunt
  exitWithMessageOnError "Grunt failed"
  cd - > /dev/null
fi

Détecter une session HTTPS

Dans App Service, une terminaison TLS/SSL se produit au niveau des équilibreurs de charge réseau. Toutes les requêtes HTTPS accèdent donc à votre application en tant que requêtes HTTP non chiffrées. Si votre logique d’application doit vérifier si les requêtes utilisateur sont chiffrées ou non, inspectez l’en-tête X-Forwarded-Proto.

Les frameworks web populaires vous permettent d’accéder aux informations X-Forwarded-* dans votre modèle d’application standard. Dans Express, vous pouvez utiliser des proxies de confiance. Par exemple :

app.set('trust proxy', 1)
...
if (req.secure) {
  // Do something when HTTPS is used
}

Accéder aux journaux de diagnostic

Pour accéder aux journaux de la console générés à l’intérieur du code de votre application dans App Service, activez la journalisation des diagnostics en exécutant la commande suivante dans Cloud Shell :

az webapp log config --resource-group <resource-group-name> --name <app-name> --docker-container-logging filesystem --level Verbose

Les valeurs possibles pour --level sont : Error, Warning, Info et Verbose. Chaque niveau suivant comprend le niveau précédent. Par exemple : Error comprend uniquement les messages d’erreur et Verbose comprend tous les messages.

Une fois la journalisation des diagnostics activée, exécutez la commande suivante pour voir le flux de journal :

az webapp log tail --resource-group <resource-group-name> --name <app-name>

Si vous ne voyez pas les journaux d’activité de la console, attendez 30 secondes et vérifiez à nouveau.

Notes

Vous pouvez également inspecter les fichiers journaux à partir du navigateur sur https://<app-name>.scm.azurewebsites.net/api/logs/docker.

Pour arrêter le streaming des journaux à tout moment, appuyez sur Ctrl+C.

Vous pouvez accéder aux journaux de la console générés à partir du conteneur.

Activez d’abord la journalisation du conteneur en exécutant la commande suivante :

az webapp log config --name <app-name> --resource-group <resource-group-name> --docker-container-logging filesystem

Remplacez <app-name> et <resource-group-name> par les noms appropriés pour votre application web.

Une fois la journalisation du conteneur activée, exécutez la commande suivante pour voir le flux de journal :

az webapp log tail --name <app-name> --resource-group <resource-group-name>

Si vous ne voyez pas les journaux d’activité de la console, attendez 30 secondes et vérifiez à nouveau.

Pour arrêter le streaming de journaux à tout moment, appuyez sur Ctrl+C.

Vous pouvez également inspecter les fichiers journaux dans un navigateur sur https://<app-name>.scm.azurewebsites.net/api/logs/docker.

Surveiller avec Application Insights

Application Insights vous permet de superviser les performances, les exceptions et l’utilisation de votre application sans modifier le code. Pour attacher l’agent Application Insights, accédez à votre application web dans le portail. Sélectionnez Application Insights sous Paramètres, puis sélectionnez Activer Application Insights. Sélectionnez ensuite une ressource Application Insights existante ou créez-en une. Enfin, sélectionnez Appliquer en bas. Pour instrumenter votre application web à l’aide de PowerShell, consultez ces instructions.

Cet agent supervise votre application de Node.js côté serveur. Pour superviser votre code JavaScript côté client, ajoutez le SDK JavaScript à votre projet.

Pour plus d’informations, consultez les notes de publication de l’extension Application Insights.

Dépannage

Quand une application Node.js en fonctionnement se comporte différemment dans App Service ou comporte des erreurs, essayez ce qui suit :

Accéder au flux de journaux.
Testez l’application localement en mode de production. App Service exécute vos applications Node.js en mode de production et dès lors, vous devez vous assurer que votre projet fonctionne comme prévu en mode de production localement. Par exemple :
- En fonction de votre package.json, différents packages peuvent être installés pour le mode de production (dependencies et devDependencies).
- Certaines infrastructures web peuvent déployer des fichiers statiques différemment en mode de production.
- Certaines infrastructures web peuvent utiliser des scripts de démarrage personnalisés lorsqu'elles s'exécutent en mode de production.
Exécutez votre application dans App Service en mode de développement. Par exemple, dans MEAN.js, vous pouvez configurer votre application en mode de développement dans le runtime en configurant le paramètre d’application NODE_ENV.

Vous n'êtes pas autorisé à voir ce répertoire ou cette page

Après avoir déployé votre code Node.js dans une application Windows native dans App Service, le message You do not have permission to view this directory or page. peut s’afficher dans le navigateur quand vous accédez à l’URL de votre application. Cela est probablement dû au fait que vous n’avez pas de fichier web.config (consultez lemodèle et un exemple).

Si vous déployez vos fichiers à l’aide de Git, ou en utilisant le déploiement ZIP avec l’automatisation de la génération activée, le moteur de déploiement génère automatiquement un fichier web.config dans la racine web de votre application (%HOME%\site\wwwroot) si l’une des conditions suivantes est remplie :

La racine de votre projet comprend un fichier package.json qui définit un script start qui contient le chemin d’un fichier JavaScript.
La racine de votre projet contient soit un fichier server.js, soit un fichier app.js.

Le fichier web.config généré est adapté au script de démarrage détecté. Pour les autres méthodes de déploiement, ajoutez ce fichier web.config manuellement. Vérifiez que le fichier est mis en forme correctement.

Si vous utilisez le déploiement ZIP (par exemple, par le biais de Visual Studio Code), veillez à activer l’automatisation de la génération, car elle n’est pas activée par défaut. az webapp up utilise le déploiement ZIP avec l’automatisation de la génération activée.

robots933456 dans les journaux

Le message suivant peut s'afficher dans les journaux du conteneur :

2019-04-08T14:07:56.641002476Z "-" - - [08/Apr/2019:14:07:56 +0000] "GET /robots933456.txt HTTP/1.1" 404 415 "-" "-"

Vous pouvez sans risque ignorer ce message. /robots933456.txt est un chemin d’URL factice utilisé par App Service pour vérifier si le conteneur est capable de traiter des requêtes. Une réponse 404 indique que le chemin d’accès n’existe pas, mais informe App Service que le conteneur est intègre et prêt à répondre aux requêtes.

Étapes suivantes

Tutoriel : Application Node.js avec MongoDB

Questions fréquentes (FAQ) sur App Service sur Linux

Ou bien, consultez les ressources supplémentaires :

Informations de référence sur les variables d’environnement et les paramètres d’application

Configurer une application Node.js pour Azure App Service

Afficher la version de Node.js

Définir la version de Node.js

Obtenir le numéro de port

Personnaliser l’automatisation de la génération

Configurer un serveur Node.js

Exécuter avec PM2

Exécuter une commande personnalisée

Exécuter npm start

Déboguer à distance

Accéder aux variables d’environnement

Exécuter Grunt/Bower/Gulp

Bower

Gulp

Grunt

Détecter une session HTTPS

Accéder aux journaux de diagnostic

Surveiller avec Application Insights

Dépannage

Vous n'êtes pas autorisé à voir ce répertoire ou cette page

robots933456 dans les journaux

Étapes suivantes

Ressources supplémentaires