Develop Node.js web apps for Azure App Service

This tutorial shows how to create a simple Node.js application and deploy it to Azure App Service from a command-line environment, such as cmd.exe or bash. The instructions in this tutorial can be followed on any operating system that can run Node.js.

Note

You can now try Azure App Service on Linux. For more information, see getting started guide.

CLI versions to complete the task

You can complete the task using one of the following CLI versions:

  • Azure CLI 1.0 – our CLI for the classic and resource management deployment models
  • Azure CLI 2.0 (Preview) - our next generation CLI for the resource management deployment model

Prerequisites

Note

You can Try App Service without an Azure account. Create a starter app and play with it for up to an hour--no credit card required, no commitments.

Create and configure a simple Node.js app for Azure

  1. Open the command-line terminal of your choice and install the Express generator for Yeoman.

     npm install -g generator-express
    
  2. CD to a working directory and generate an express app using the following syntax:

     yo express
    

    Choose the following options when prompted:

    ? Would you like to create a new directory for your project? Yes
    ? Enter directory name {appname}
    ? Select a version to install: MVC
    ? Select a view engine to use: Jade
    ? Select a css preprocessor to use (Sass Requires Ruby): None
    ? Select a database to use: None
    ? Select a build tool to use: Grunt

  3. CD to the root directory of your new app and start it to make sure it runs in your development environment:

     npm start
    

    In your browser, navigate to http://localhost:3000 to make sure that you can see the Express home page. Once you've verified your app runs properly, use Ctrl-C to stop it.

  4. Open the ./config/config.js file from the root of your application and change the production port to process.env.port; your production property in the config object should look like the following example:

     production: {
         root: rootPath,
         app: {
             name: 'express1'
         },
         port: process.env.port,
     }
    
    Note

    By default, Azure App Service runs Node.js applications with the production environment variables (process.env.NODE_ENV="production". Therefore, your configuration here lets your Node.js app in Azure respond to web requests on the default port that iisnode listens.

  5. Open ./package.json and add the engines property to specify the desired Node.js version.

     "engines": {
         "node": "6.9.1"
     }, 
    
  6. Save your changes, then initialize a Git repository in the root of your application and commit your code:

     git add .
     git add -f config
     git commit -m "{your commit message}"
    

Deploy your Node.js app to Azure

  1. Log in to Azure (you need Azure CLI 2.0 Preview):

     az login
    

    Follow the prompt to continue the login in a browser with a Microsoft account that has your Azure subscription.

  2. Set the deployment user for App Service. You will deploy code using these credentials later.

     az appservice web deployment user set --user-name <username> --password <password>
    
  3. Create a new resource group. For this node.js tutorial, you don't really need to know what it is.

     az group create --location "<location>" --name my-nodejs-app-group
    

    To see what possible values you can use for <location>, use the az appservice list-locations CLI command.

  4. Create a new "FREE" App Service plan. For this node.js tutorial, just know that you won't be charged for web apps in this plan.

     az appservice plan create --name my-nodejs-appservice-plan --resource-group my-nodejs-app-group --sku FREE
    
  5. Create a new web app with a unique name in <app_name>.

     az appservice web create --name <app_name> --resource-group my-nodejs-app-group --plan my-nodejs-appservice-plan
    
  6. Configure local Git deployment for your new web app with the following command:

     az appservice web source-control config-local-git --name <app_name> --resource-group my-nodejs-app-group
    

    You will get a JSON output like this, which means that the remote Git repository is configured:

     {
     "url": "https://<deployment_user>@<app_name>.scm.azurewebsites.net/<app_name>.git"
     }
    
  7. Add the URL in the JSON as a Git remote for your local repository (called azure for simplicity).

     git remote add azure https://<deployment_user>@<app_name>.scm.azurewebsites.net/<app_name>.git
    
  8. Deploy your sample code to the azure Git remote. When prompted, use the deployment credentials you configured earlier.

     git push azure master
    

    The Express generator already provides a .gitignore file, so your git push doesn't consume bandwidth trying to upload the node_modules/ directory.

  9. Finally, launch your live Azure app in the browser:

     az appservice web browse --name <app_name> --resource-group my-nodejs-app-group
    

    You should now see your Node.js web app running live in Azure App Service.

    Example of browsing to the deployed application.

Update your Node.js web app

To make updates to your Node.js web app running in App Service, just run git add, git commit, and git push like you did when you first deployed your web app.

How App Service deploys your Node.js app

Azure App Service uses iisnode to run Node.js apps. Azure CLI 2.0 Preview and the Kudu engine (Git deployment) work together to give you a streamlined experience when you develop and deploy Node.js apps from the command line.

  • You can create an iisnode.yml file in your root directory and use it to customize iisnode properties. All configurable settings are documented here.
  • At git push azure master, Kudu automates the following deployment tasks:

    • If package.json is in the repository root, run npm install --production.
    • Generate a Web.config for iisnode that points to your start script in package.json (e.g. server.js or app.js).
    • Customize Web.config to ready your app for debugging with Node-Inspector.

Use a Node.js framework

If you use a popular Node.js framework, such as Sails.js or MEAN.js to develop apps, you can deploy those to App Service. Popular Node.js frameworks have their specific quirks, and their package dependencies keep getting updated. However, App Service makes the stdout and stderr logs available to you, so you can know exactly what's happening with your app and make changes accordingly. For more information, see Get stdout and stderr logs from iisnode.

The following tutorials will show you how to work with a specific framework in App Service:

Use a specific Node.js engine

In your typical workflow, you tell App Service to use a specific Node.js engine as you normally would in package.json. For example:

"engines": {
    "node": "6.9.1"
}, 

The Kudu deployment engine determines which Node.js engine to use in the following order:

  • First, look at iisnode.yml to see if nodeProcessCommandLine is specified. If yes, then use that.
  • Next, look at package.json to see if "node": "..." is specified in the engines object. If yes, then use that.
  • Choose a default Node.js version by default.

For the updated list of all supported Node.js/NPM versions in Azure App Service, access the following URL for your app:

https://<app_name>.scm.azurewebsites.net/api/diagnostics/runtime
Note

It is recommended that you explicitly define the Node.js engine you want. The default Node.js version can change, and you may get errors in your Azure web app because the default Node.js version is not appropriate for your app.

Get stdout and stderr logs from iisnode

To read iisnode logs, follow these steps.

Note

After completing these steps, log files may not exist until an error occurs.

  1. Open the iisnode.yml file that Azure CLI 2.0 Preview provides.
  2. Set the two following parameters:

     loggingEnabled: true
     logDirectory: iisnode
    

    Together, they tell iisnode in App Service to put its stdout and stderror output in the D:\home\site\wwwroot*iisnode* directory.

  3. Save your changes, then push your changes to Azure with the following Git commands:

     git add .
     git commit -m "{your commit message}"
     git push azure master
    

    iisnode is now configured. The next steps show you how to access these logs.

  4. In your browser, access the Kudu debug console for your app, which is at:

     https://{appname}.scm.azurewebsites.net/DebugConsole 
    

    This URL differs from the web app URL by the addition of ".scm." to the DNS name. If you omit that addition to the URL, you will get a 404 error.

  5. Navigate to D:\home\site\wwwroot\iisnode

    Navigating to the location of the iisnode log files.

  6. Click the Edit icon for the log you want to read. You can also click Download or Delete if you want.

    Opening an iisnode log file.

    Now you can see the log to help you debug your App Service deployment.

    Examining an iisnode log file.

Debug your app with Node-Inspector

If you use Node-Inspector to debug your Node.js apps, you can use it for your live App Service app. Node-Inspector is preinstalled in the iisnode installation for App Service. And if you deploy through Git, the auto-generated Web.config from Kudu already contains all the configuration you need to enable Node-Inspector.

To enable Node-Inspector, follow these steps:

  1. Open iisnode.yml at your repository root and specify the following parameters:

     debuggingEnabled: true
     debuggerExtensionDll: iisnode-inspector.dll
    
  2. Save your changes, then push your changes to Azure with the following Git commands:

     git add .
     git commit -m "{your commit message}"
     git push azure master
    
  3. Now, just navigate to your app's start file as specified by the start script in your package.json, with /debug added to the URL. For example,

     http://{appname}.azurewebsites.net/server.js/debug
    

    Or,

     http://{appname}.azurewebsites.net/app.js/debug
    

More resources