Installing and Running node.js applications within IIS on Windows - Are you mad?

Some folks on our team have been working on making node.js work awesomely on Windows. There's a few questions you might have.

First, what's node.js?

If you're not familiar with node.js, it's a new web programming toolkit that everyone's talking about. It's the one that makes you feel not hip if you don't know what it is. Like Ruby on Rails was a few years back. Folks called it "Node" and it's basically server-side JavaScript. The idea is that if you are doing a bunch of JavaScript on the client and you do JavaScript all day, why not do some JavaScript on the server also. One less thing to learn, I suppose.

If you are an ASP.NET programmer, you can think of node.js as being like an IHttpHandler written in JavaScript. For now, it's pretty low-level. It's NOT an HttpHandler, but I'm using an analogy here, OK? Here's a lovely article by Brett McLaughlin that goes into more detail about Node.js and what it is. His subtitle is "Node isn't always the solution, but it does solve some important problems" and that's just exactly it.

UPDATE 1: Why does node.js matter?

Why bother with node at all? There's a number of interesting aspects to node as it sits. It uses a very fast JavaScript engine called V8, but more importantly its I/O is asynchronous and event-driven which contrasts with typical synchronous code.

For example, a naive hello world HttpHandler in ASP.NET that "does some work" for a few seconds (gets a file, accesses a service, etc) could look something like this:

public class SimpleHandler : IHttpHandler 
{
    public void ProcessRequest(HttpContext context)
    {
        Thread.Sleep(2000); //Do something that takes a while
        context.Response.Write("Hello from SimpleHandler");
    }

    public bool IsReusable { get { return true; } }
}

And this is usually fine for most stuff. However, when I push this HARD with a load testing tool and a thousand virtual clients, I can barely get 60 requests a second. The request thread is tied up waiting for the "work" to happen and everyone else gets in line. I'm using up ASP.NET pool. It'd be nice if the work would get handled and someone would "call me back" when it's finished. It's like waiting on hold for tech support. You are effectively blocked as you wait for them to pick up their end. Wouldn't it be nice if they just called you back when they were ready?

ASP.NET has always been able to do things (see this MSDN article from 2003 on Async Handlers) with IHttpAsyncHandler but it's always been a bit hard and almost no one knows about it. With the Async CTP and the Task libraries built into .NET, you can build a nicer abstraction on top of IHttpAsyncHandler. Ayende has a simple example AbstractAsyncHandler (there's many of these out there, including a few in our own tools, some things in MVC, and some things in SignalR (more on that soon)) that we can use to do similar work. This example could also do other more complex and pertinent things like file IO, db IO or calling a web service. This is a naive example that doesn't map exactly to the node one below, but it makes the point. Plus, it's nice to look at.

public class SimpleAsyncAyendeHandler : AbstractAsyncHandler
{
    protected override async Task ProcessRequestAsync(HttpContext context)
    {
        await TaskEx.Delay(2000);
        await context.Response.Output.WriteAsync("Hello from Ayende and Scott");
    }
}

Pointing the same 1000 virtual clients at this handler gives me 500 requests a second, which makes sense as a request takes 2 seconds to finish. If we were doing I/O or other more complex and long running things than waiting, this scales better than the first example. Doing asynchronous code in .NET as well as parallelism is much easier than before, as evidenced by the two lines of  code above and the simplicity of Ayende's small example. The fact that this kind of thing is easy and elegant in node is an attractive thing about node.

Node loves asynchrony, and uses JavaScript callbacks to provide asynchrony in a pleasant way. You use events and callbacks in JavaScript already on the client, why not use them on the server? Here's an example from Marc Fasel's blog on the topic.

First, some synchronous file work via Marc:

var fs = require('fs'), filenames, i, processId;

filenames = fs.readdirSync(".");
for (i = 0; i < filenames.length; i++) {
    console.log(filenames[i]);
}
console.log("Ready.");

processId = process.getuid();

And the same work using an asynchronous pattern that may look familiar!

var fs = require('fs'), processId;

fs.readdir(".", function (err, filenames) {
    var i;
    for (i = 0; i < filenames.length; i++) {
        console.log(filenames[i]);
    }
    console.log("Ready.");
});

processId = process.getuid();

The I/O happens and the callback function that's dependant on the result is executed when the I/O is finished. Powerful stuff.

Why would I want node.js to run on Windows and IIS?

Tomasz Janczuk is working on the iisnode project lately. You might think that Windows and node don't belong together. "That's just wrong! What are they thinking? I thought IIS was all about .NET?" Well, you may recall I spoke at CodeMash a few years back on IIS7 and PHP and did a screencast showing how IIS7, PHP and FastCGI could push many thousands of requests a second. The IIS folks, the Windows folks, the Azure folks, want to make sure everything runs well on Windows. Remember, we sell Windows, so it's good if it does many things well. ;)

Why bother getting node to run on IIS? Tomasz says it best:

Some of the advantages of hosting node.js applications in IIS using the iisnode module as opposed to self-hosting node.exe processes include:

• Process management. The iisnode module takes care of lifetime management of node.exe processes making it simple to improve overall reliability. You don’t have to implement infrastructure to start, stop, and monitor the processes.
• Scalability on multi-core servers. Since node.exe is a single threaded process, it only scales to one CPU core. The iisnode module allows creation of multiple node.exe processes per application and load balances the HTTP traffic between them, therefore enabling full utilization of a server’s CPU capacity without requiring additional infrastructure code from an application developer.
• Auto-update. The iisnode module ensures that whenever the node.js application is updated (i.e. the script file has changed), the node.exe processes are recycled. Ongoing requests are allowed to gracefully finish execution using the old version of the application, while all new requests are dispatched to the new version of the app.
• Access to logs over HTTP. The iisnode module provides access the output of the node.exe process (e.g. generated by console.log calls) via HTTP. This facility is key in helping you debug node.js applications deployed to remote servers.
• Side by side with other content types. The iisnode module integrates with IIS in a way that allows a single web site to contain a variety of content types. For example, a single site can contain a node.js application, static HTML and JavaScript files, PHP applications, and ASP.NET applications. This enables choosing the best tools for the job at hand as well progressive migration of existing applications.
• Minimal changes to node.js application code. The iisnode module enables hosting of existing HTTP node.js applications with very minimal changes. Typically all that is required is to change the listed address of the HTTP server to one provided by the iisnode module via the process.env.PORT environment variable.
• Integrated management experience. The issnode module is fully integrated with IIS configuration system and uses the same tools and mechanism as other IIS components for configuration and maintenance.

  In addition to benefits specific to the iisnode module, hosting node.js applications in IIS allows the developer to benefit from a range of IIS features, among them:

  • port sharing (hosting multiple HTTP applications over port 80)
  • security (HTTPS, authentication and authorization)
  • URL rewriting
  • compression
  • caching
  • logging

These are all compelling, but the most interesting bit here, in my opinion, is integration. The iisnode module is a proper IIS module, just like ASP.NET and PHP. This means you can have a single website that has multiple kinds of content. Restated from above:

For example, a single site can contain a node.js application, static HTML and JavaScript files, PHP applications, and ASP.NET applications.

Sometimes folks freak out when I say you can have an ASP.NET WebForms app and a ASP.NET MVC app in the same AppPool as a "hybrid." Frankly, Dear Reader, people don't even realize the power and flexibility of IIS. When you plug in something new like node but run it the way you run other things it inherits all the coolness of the outer container, in this case, IIS.

Fine, you got me, how do I run node.js on Windows?

I'm assuming you are running IIS7.

• Go download node.exe, and put it in c:\node
• Go download a build of iisnode.
• Unzip iisnode's zip into \inetpub\iisnode
  • (that was my idea, not sure if it's the best place)
• From an Administrator Command Line, run install.bat.

The install.bat will:

• unregister existing "iisnode" global module from your installation of IIS if such registration exists
• register iisnode as a native module with your installation of IIS
• install configuration schema for the "iisnode" module
• remove existing "iisnode" section from system.webServer section group in applicationHost.config
• add the "iisnode" section within the system.webServer section group in applicationHost.config
• delete the iisnode web application if it exists
• add a new site iisnode to IIS

No warranties! Be careful, you're living on the edge. Remember, you're reading this stuff on some random dude's blog.

WARNING: I couldn't figure out the right permissions for the AppPool and the File System so I wimped out and gave my local AppPool "SYSTEM" permissions. This is awful and totally my fault. I filed an issue on the iisnode GitHub and I'll fix it and update this post when I hear back.

I made a new AppPool just for node, gave it SYSTEM access, then assigned the Node Site to this new AppPool. Your site should look like:

And if you click on Modules for this Site in IIS7 you should see iisnode as a native module:

At this point, you should be able to hit http://localhost/node/helloworld/hello.js and get back:

Hello, world! [helloworld sample]

The contents of which are simply:

var http = require('http');

http.createServer(function (req, res) {
    res.writeHead(200, {'Content-Type': 'text/plain'});
    res.end('Hello, world! [helloworld sample]');
}).listen(process.env.PORT);  

Lovely.

Fooling around with WCAT (Web Capacity Analysis Tool) and node.

Disclaimer: To be clear, this is so very fooling around. This is just to show that it works and it can do the basics really fast. I'm not doing a benchmark nor am I saying "this works better than this other thing." Remember, they just got started recently porting node itself to Windows, and Tomasz and friends are just beginning their work. So, don't overreach. That said, the preliminary work they are doing is really impressive.

I couldn't help myself. I mean, it's one thing to install a helloworld of some new thing, run it once and go "OK, that runs." It's another to pound it until it says "Uncle." After I got the hello world stuff working, I wanted to do some poor man's stress testing to see what the players involved did.

First, I installed WCAT, a free Web Capacity Analysis Tool from the IIS team.

1. WCAT 6.3 x86
2. WCAT 6.3 x64

Warning. This is a command-line only tool and it's really persnickety when you run it. It's confusing and it took me a minute to setup.  Here's the steps I took after installing. This is all from an Administrator Command Prompt. Note also that I'm doing this all on one machine, which is cheesy, but remember, it is a GOM.

1. cscript //H:Cscript
2. wcat.wsf –terminate –update –clients localhost
3. Then I made a folder I called \nodetests and I put these three files in it:

wcat.bat

pushd C:\Users\Scott\Desktop\nodetests
"c:\program files\wcat\wcat.wsf" -terminate -run -clients localhost -f settings.ubr -t nodescenario.ubr -s localhost -singleip  -o C:\Users\Scott\Desktop\nodetests
pause

nodescenario.ubr (or call it whatever you want)

This is so basic. It just beats on the four sample applications for a while.

scenario
{
  name    = "node_fun";

    warmup      = 30;
    duration    = 90;
    cooldown    = 30;

    default  
    {
        setheader
        {
            name    = "Connection";
            value   = "keep-alive";
        }
        setheader
        {
            name    = "Host";
            value   = server();
        }
        version     = HTTP11;
        statuscode  = 200;
        close       = ka;
    }
    
    transaction
    {
        id = "foo";
        weight = 1000;
        request
        {
            url = "/node/logging/hello.js";
        }
    }
    transaction
    {
        id = "bar";
        weight = 2000;
        request
        {
            url = "/node/helloworld/hello.js";
        }
    }
    transaction
    {
        id = "baz";
        weight = 2000;
        request
        {
            url = "/node/defaultdocument/";
        }
    }    
    transaction
    {
        id = "bat";
        weight = 2000;
        request
        {
            url = "/node/configuration/hello.js";
        }
    }    
}

settings.ubr

I just copied in the one from samples and uncommented out and changed (and tweaked during testing) these lines:

server         = "hexpower7";
clients        = 1;
virtualclients = 8;

Now, run the Test

Next, I ran wcat.bat as an Administrator...you can see all the little node.exe's firing up. I've got a

(Remember they are running as SYSTEM because I was unable to figure out the right permissions. That's my bad, no one else's. I'll figure it out one day.)

Here's the WCAT tool's console output...I'm able to consistently do 10,000 hello worlds a second and ended up with just under a million normal requests and responses in 90 seconds. That's a lot of hello worlds.

Remember Hanselman's Rule of Scale.

"If you do nothing, you can scale infinitely." - Me

Of course, this is all local on a fast machine. This is just hello world (with some logging) so it's not testing node much, nor IIS much, but rather the collaboration between the whole system, IIS, iisnode, and node itself.

Aside: an ASP.NET IHttpHandler doing the exact same thing on this same machine gets 22,500 requests a second, so node and iisnode has some room to improve, which is great.

Here's the node/iisnode results:

There's a lot of things I could configure on both sites, number of clients, virtual clients, as well as iisnode-specific settings (which are, nicely enough, managed in a web.config:

<configuration>
  <system.webServer>
    <handlers>
      <add name="iisnode" path="hello.js" verb="*" modules="iisnode" />
    </handlers>
    <iisnode      
      nodeProcessCommandLine="%systemdrive%\node\node.exe"
      maxProcessCountPerApplication="4"
      maxConcurrentRequestsPerProcess="1024"
      maxPendingRequestsPerApplication="1024"
      maxNamedPipeConnectionRetry="3"
      namedPipeConnectionRetryDelay="2000"      
      asyncCompletionThreadCount="4"
      initialRequestBufferSize="4096"
      maxRequestBufferSize="65536"
      uncFileChangesPollingInterval="5000"
      gracefulShutdownTimeout="60000"
      loggingEnabled="true"
      logDirectoryNameSuffix="logs"
      maxLogFileSizeInKB="128"
      appendToExistingLog="false"
     />
   </system.webServer>
</configuration>

This is pretty cool stuff. I like that the team I work with is excited to make things work well on IIS and I'm stoked that I can mess around with node now without firing up VMs. I'll report back as I learn more!

Related Links

• Download node.js
• The iisnode project on GitHub
  • Download the iisnode binaries
• Tomasz's blog

---

© 2011 Scott Hanselman. All rights reserved.