Thursday, May 31, 2012

Develop on Mac, host on GitHub, and deploy to Windows Azure with git-azure

If you are like most node.js developers, you develop your code on a Mac and host it on GitHub. With the git-azure project I started recently, you can now deploy that code to Windows Azure directly from your development environment.

What is git-azure?

Git-azure is a tool and runtime environment that allows deploying multiple node.js applications into Windows Azure Worker Role from MacOS using Git in seconds.

A good way to understand how git-azure can help you deploy and manage node.js applications is to watch the 7 minute video below. 

Git-azure consists of three components: a git-azure runtime, a command line tool integrated into git toolchain, and your own Git repository (likely on GitHub).

The git-azure runtime is a pre-packaged Windows Azure service that runs HTTP and WebSocket reverse proxy on an instance of Windows Azure Worker Role. The proxy is associated with your Git repository that contains one or more node.js applications. Incoming HTTP and WebSocket requests are routed to individual applications following a set of convention based or explicit routing rules.

The git-azure command line tool is an extension of the git toolchain and accessible with the git azure command. It allows you to perform a one-time deployment of git-azure runtime associated with your Git repository to Windows Azure, after which adding, modifying, and configurting applications is performend with regular git push commands and take seconds. The git azure tool also helps with scaffolding appliations, configuring routing and SSL, and access to Windows Azure Blob Storage.

Motivation and direction

I have started the git-azure project as a platform for experimenting with a variety of ideas related to streamlining development and deployment of applications to Windows Azure. Current focus is primarily on node.js applications.

Key design decisions at this point were derived from two observations:

The initial release of git-azure (v0.2.0) supports the following scenarios and functionality:

  • develop on Mac, host code on GitHub, and deploy from Mac to Windows Azure Worker Role,
  • tight integration of the client side tool with the git toolchain,
  • run multiple self-hosted node.js applications behind an HTTP reverse proxy on a single VM running in Windows Azure,
  • after initial provisioning of the VM, add and modify applications in seconds using git push and a post-receive hook,
  • support for HTTP and WebSocket traffic,
  • SSL support out of the box,
  • customization of SSL credentials per host name using Server Name Identification (SNI),
  • administrative access to the VM using RAS (currently requires Windows client).

In the nearest future, I am planning to look at the following:

  • real time access to application logs and diagnostic information,
  • SSH access to the VM for administration,
  • scale out to multiple VM instances and customization of VM size

How to learn more and engage

Do check out the walkthrough at the project site at for hands-on experience with the git-azure tool and runtime as well as access to the code.

Please share your thoughts or ideas by filing an issue, or consider contributing to the project. I do take contributions.

Special thanks

Special thanks to Glenn Block, the first user of git-azure, for valuable feedback and ideas, as well as helping spread the news about git-azure across several node.js events he spoke at recently in Europe.

Also a big thank you to Matias Woloski who was kind enough to talk about git-azure during JSConf.AR 2012.

Thursday, May 10, 2012

YAML configuration support in iisnode

Upon popular demand for YAML configuration (or rather lack of demand for angle brackets of web.config), iisnode v0.1.20 adds support for specifying configuration options in a YAML file. This allows you to use an established, user-friendly format to control most aspects of hosting node.js applications in IIS on Windows using iisnode.


You can use iisnode.yml file to control several configuration options for iisnode. For a full and current list with a description see here.

# The optional iisnode.yml file provides overrides of 
# the iisnode configuration settings specified in web.config.

node_env: production
nodeProcessCommandLine: "c:\program files\nodejs\node.exe"
interceptor: "c:\program files\iisnode\interceptor.js"
nodeProcessCountPerApplication: 1
maxConcurrentRequestsPerProcess: 1024
maxNamedPipeConnectionRetry: 24
namedPipeConnectionRetryDelay: 250
maxNamedPipeConnectionPoolSize: 512
maxNamedPipePooledConnectionAge: 30000
asyncCompletionThreadCount: 0
initialRequestBufferSize: 4096
maxRequestBufferSize: 65536
watchedFiles: *.js;iisnode.yml
uncFileChangesPollingInterval: 5000
gracefulShutdownTimeout: 60000
loggingEnabled: true
logDirectory: iisnode
debuggingEnabled: true
debuggerPortRange: 5058-6058
debuggerPathSegment: debug
maxLogFileSizeInKB: 128
maxTotalLogFileSizeInKB: 1024
maxLogFiles: 20
devErrorsEnabled: true
flushResponse: false
enableXFF: false

The iisnode.yml configuration file is not a replacement of web.config: both can exist at the same time. However, if iisnode.yml is present, its settings override the values specified in the system.webServer\iisnode section of web.config.


By default, when the iisnode.yml configuration file changes, iisnode will gracefully recycle the node.js application. Active requests will be allowed to finish, but all new requests will be handled by a newly created node.js process that uses new configuration values.

So why do I still need web.config?

Even if you use iisnode.yml file to configure your node.js application running in iisnode, you still need to include a web.config file. Since IIS is a hosting environment that supports a vast (and extensible) variety of content types running side by side (static files, ASP.NET apps, PHP, node.js , …), web.config is a mechanism to tell IIS that your node.js entry point (e.g. server.js) should be handled by iisnode. In addition, web.config provides the full control over how IIS behaves and can add unique value to your node.js application as explained below.

The good news is that in majority of situations you can use a boilerplate web.config below and never come back to it, relying solely on iisnode.yml for configuration of node.js applications running in IIS.

<?xml version="1.0" encoding="utf-8"?>
<add name="iisnode" path="server.js" verb="*" modules="iisnode"/>
<rule name="LogFile" patternSyntax="ECMAScript" stopProcessing="true">
<match url="iisnode"/>
<rule name="NodeInspector" patternSyntax="ECMAScript" stopProcessing="true">
<match url="^server.js\/debug[\/]?" />
<rule name="StaticContent">
<action type="Rewrite" url="public{{REQUEST_URI}}"/>
<rule name="DynamicContent">
<add input="{{REQUEST_FILENAME}}" matchType="IsFile" negate="True"/>
<action type="Rewrite" url="server.js"/>

The web.config above has the following effect:

  1. It specifies server.js as the entry point to your node.js application.
  2. It redirects all requests for URLs that map to physical files in the “public” subdirectory to an IIS static file handler. Using IIS static file handler has a large performance benefit compared to serving static content from within a node.js application. The handler leverages IIS and OS low level caching mechanisms which offer superb performance.
  3. It allows IIS to serve the log files that capture output of a node.js application as static files such that you can access them over HTTP. By default, if your server.js entry point is reached at, the log files would be accessible at
  4. It exposes the built-in node-inspector debugger at Learn more about debugging with iisnode.
  5. It sends all other HTTP requests to be processed by your node.js application in server.js.

Try it out

Get your copy if iisnode at and give YAML config a try!

My Photo
My name is Tomasz Janczuk. I am currently working on my own venture - Mobile Chapters ( Formerly at Microsoft (12 years), focusing on node.js, JavaScript, Windows Azure, and .NET Framework.