One does not simply run Node.js on Microsoft Azure

shawn posted some pics said
9

We've been running Node.js on Microsoft Azure for about a year now on mediocre.com and recently launched meh.com using the same tech stack. Thought I'd share some of the tips, tricks, and things we've learned along the way.

You might be asking, "Node.js on Azure? Why?" I get this from time to time. I had a variety of reasons for going this route. Here's a big one: I've had a career's worth of experience building sites using .NET on AWS and wanted to try something different.

Let's set aside the reasoning behind running Node.js on Microsoft Azure for now and dive into the things you're gonna want to know if you end up going the same direction. If you're looking for the TL;DR here it is in meme form:

Docs

First, if you're going to run Node.js on Microsoft Azure you should read the docs at the Azure Node.js Dev Center. Over the past 18 months I've read them cover-to-cover dozens of times. They haven't changed much during that time which makes me wonder how much effort Microsoft is putting into Node.js on Azure these days. It's a pretty good set of docs though. They're certainly not comprehensive, but they're good getting started and tutorial material.

Support

I'll keep this part short. We're a Microsoft BizSpark member and I expected more help when I needed it. If you want to read more I've been fairly vocal about the mediocre support we've experienced.

Cloud Services vs Web Sites vs Virtual Machines

There's a few ways you can run Node.js apps on Azure. I would recommend using "Web Sites" when you can. It's the part of Azure where Microsoft is doing the most management for you, but you also have the least control.

Everything I'm going to cover here will be about "Cloud Services". We decided to run our public facing web applications and internal REST services using Cloud Services so that we could keep them inside a Virtual Network for security purposes.

Development

We do all our development on Mac OS X. The main reason I'm pointing this out is because Microsoft has created some tooling and support for Node.js inside Visual Studio which we don't use. Things might be easier with Visual Studio.

Build and deploy a Node.js application to an Azure Cloud Service

Once you're ready to get started working on a Node.js Azure Cloud Service, you'll probably land at this documentation. It's over two years old now, but it's where we got started.

The first thing you'll notice is that this documentation is written for Windows and PowerShell (not Mac). I created a Windows VM in Azure so I could run through the tutorial, then I pushed the files it created to GitHub and continued development on my Mac.

Follow all the steps in the tutorial and you'll end up with a working Node.js app running on an Azure Cloud Service.

IISNode

I mentioned the Azure docs for Node.js are about two years out of date. So are the PowerShell scripts and the dependencies they setup. You're going to want to update some things.

When you run Node.js on an Azure Cloud Service you're running Node.js on Windows in IIS using IISNode. The version that's installed by default is v0.1.21 which is over two years old. You'll want to upgrade to something like v0.2.14 before your app starts taking on traffic and runs into memory heap corruption issues like we did.

node.exe

The version of node.exe that's installed by default is really, really old (v0.6.20). You'll probably want to use the latest v0.10.x version. Here's how we got this to work.

iisnode.yml vs Web.cloud.config

IISNode supports YAML configuration through an iisnode.yml file. It also supports configuration through the Web.cloud.config file. Since you need to have a Web.cloud.config file for IIS we do all our configuration there and ditched the iisnode.yml file to avoid any confusion.

Here's IISNode settings we changed in our Web.cloud.config file:

Error Pages

IIS loves, loves, loves to be all up in your error pages.

But we have a little troll just waiting to sing his heart out when something goes terribly wrong

Here's what we did to tell IIS to chill, Winston... we'll handle error pages:

Deployment

This is the worst part of running Node.js on a Microsoft Azure Cloud Service in my opinion. Here's my top three reasons why:

Final Thoughts

Can't say I'd recommend Node.js on Azure Cloud Services to other devs. As you can see, this was a pain in the ass to get all figured out. That said, we do enjoy working with other features of Azure. My personal favorite is the Azure Service Bus which is fantastic and we use it a ton. I wish Microsoft supported Azure Web Sites inside a Virtual Network the same way AWS supports Elastic Beanstalk inside a VPC.

Hoping we'll see more Node.js support on Microsoft Azure in the future, until then I hope these tips and tricks might save some devs a few hours.