Deploying Node applications to Azure website seems simple. Just set up continuous deployment on the Azure Portal. Azure will build, test and automatically deploy your app when you check in code. Everything runs so well until you open a browser, navigate to the website url and see this: 500 internal server error. That was exactly the case we had in the last project. The application was written in node & express with dependancies to 52 npm packages including babel, redis, new relic, gulp, webpack. It works like a charm on local servers, just not on Azure website with git deployment. As usual, most documentation we found online are about “Hello world” which won’t help much with a production problem. Here are some of the steps we used to diagnose and analysis the deploy problem and make it work.

Test compilation on windows

During npm install, some node modules with native extensions will be compiled to match the hosting OS and architecture(x86 or x64). If the application is developed on Mac OS, Linux and deploy to Azure website, first thing to do is to confirm that every module is compatible with Windows platform.

##web.config file
Under the hood, Azure website hosts node.js apps with iisnode. You need a web.config to config iisnode. If you use git deployment, when Azure detects an app.js or server.js file, it will automatically generate a web.config. Or you can add a custom one manually. Open the web.config file, and check the handlers section. Make sure it points to the correct application entry point.

<handlers>
    <add name="iisnode" path="app.js" verb="*" modules="iisnode"/>
</handlers>

Environment variables

You can set environment variables through a website portal or Azure CLI. The easiest way to check their value is through website portal, under config section, choose app settings. Or if you are using Azure CLI, run

azure site config list your-site

Make sure there is no PORT setting. iisnode will use this variable to pipe IIS to your app.
Also check value of WEBSITE_NODE_DEFAULT_VERSION, it sets default node version used by the target website.

Check in node_modules

When using git deployment, normally we don’t check in node_modules. However, according to this Azure documentation

Azure Websites does not support all native modules and might fail at compiling those with very specific prerequisites.

So if all the about steps don’t help, you might want to test it out by checking in you node_modules. Remember, before checkin, run npm install on a Windows platform with some architecture of you website.

Enable Application log

Add the following to your iisnode.yml

node_env: production
loggingEnabled: true
devErrorsEnabled: true

Then you can use Azure CLI to live stream the logs

$ azure site log tail sampleBlog

Debug with Kudu

Kudu is the engine behind git deployments in Azure Web Sites.
Every Azure web site has an associated ‘scm’ service site at https://your-site.scm.azurewebsites.net/. It provides a set of tools for troubleshooting and analysis your node.js website. You can:

• Launch the diagnostic console
• Check runtime environment
• Monitor active node process

Open the debug console, choose CMD or powershell.
Then start you app with node.exe directly

$ cd D:\home\site\wwwroot> 
$ node app.js

If you see an error from a node module, it might be caused by either wrong node version or corrupt node_module. Check the current node version

$ node -v

Make sure it is your target version. Run npm install for the failed module if necessary. Once the app starts from console, you can close it and restart your website. Open a browser and see your website start working.