Windows Server 2012

Hosting Node.js Applications on Windows Server 2012, Complete with Git Deployment and Remote Debugging - Part 3

Alex Ford

Jul 13, 2013 • 12 min read

Quick Links

Part 1 - Setting up Virtual Machine
Part 2 - Installing IIS, Git, Node.js, and IISNode
Part 3 - Installing Kudu

Unfortunately, Kudu doesn't have a fancy installer like everything else we've installed so far. We actually have to build Kudu from source. The easiest way to do that is to install Visual Studio 2012 Express For Web first.

Installing Visual Studio 2012 Express For Web

First head over to this link and click "Install now".

This will take you to a page with a big green "Install Now" button. This will install the Microsoft Web Platform Installer (WebPI) which will then install Visual Studio 2012 Express For Web. Simply accept all the defaults in the installation wizard. It will take a while to download and install so be patient. When starting Visual Studio Express 2012 for the first time it will ask you for a product key. VS Express is free, you just have to click "Register online" next to the product key box to get a free product key emailed to you.

Once you have your key just paste it in and click next.

Getting Kudu's Source

The first thing we need to do to install Kudu is pull down the latest source. Open up the Windows Command Prompt and run the following.

git clone https://github.com/projectkudu/kudu.git c:\code\kudu

This will pull down the Kudu source code and store it in a folder located at "C:\Code\Kudu".

Modifying Kudu's Source and Building

It's finally time to open up the Kudu project for the first time. Run Visual Studio Express 2012 For Web and click "Open Project". Navigate to the Kudu project file located at "C:\Code\Kudu\Kudu.sln" and open it up. Once the project opens you'll see the project structure in the solution explorer window in the right-hand side. By default all the nodes in solution explorer are expanded. Collapse all of them and you should see a view like this.

Expand the node for the Kudu.Web project and navigate to "Kudu.Web > App_Start > Startup.cs". This file contains Ninject bindings for the project. If you don't know what that is don't worry about it. Toward the bottom you should see a line that looks like this.

kernel.Bind<ICredentialProvider>().ToConstant(new BasicAuthCredentialProvider("admin", "kudu"));

Change "admin" to the username you created when setting up your virtual machine (the Windows user). Also change "kudu" to the password you created.

Now go to the "BUILD" menu at the top of Visual Studio and select "Build Solution".

Once the build is complete you should see output like this in the output window.

As long as it says "14 succeeded" then all projects in the Kudu solution compiled successfully.

Setting up Kudu in IIS

We're almost done, but we still have some configuring to do. First we need to open up IIS and setup Kudu. To do this go back to Server Manager. If you closed Server Manager then you will have to wait a minute for the IIS tab to appear after you open it again.

Click the IIS tab. You should see one item in the "SERVERS" list. Right-click it and navigate to "Internet Information Servies (IIS) Manager".

IIS comes with a default web site already configured. We are going to delete the default website and add our own. In the left pane of IIS Manager expand the server node, then expand the "Sites" node. Right-click "Default Web Site" and select "Remove". Next, right-click the server node and choose "Add Website...".

You should now see a window allowing you to name your website. Make your window look like mine.

We are creating a website in IIS that maps to the Kudu web interface. The Kudu web interface allows us to manage our applications that we want to deploy using Kudu. Once you've made your form look like the one in the above screenshot simply click OK.

Next select the website you just created and click on the "Authentication" icon.

Select "Anonymous Authentication" and click "Disable" on the right.

We don't want anyone on the internet to be able to mess with your Kudu installation so we want to disable anonymous authentication. Next we want to enable "Basic Authentication".

All we've done is enable basic plain-text authentication. Down the road if you want to purchase an SSL certificate for your server you can make this more secure, but that is outside the scope of this tutorial.

Next click on "Application Pools".

Select "Kudu Manager" from the list and click "Advanced Settings..." on the right-hand side. This will open up a settings dialog. Navigate to the "Identity" field and select the little button next to "ApplicationPoolIdentity".

This will open yet another dialog. Change the selected value under "Built-in account:" to "LocalSystem".

Setting up your first application in Kudu

Now that Kudu is up we need to access the interface. Open up the browser and navigate to "http://localhost/". It will prompt you for a username and password. Enter the credentials you setup when creating your virtual machine (your server's Windows credentials). You should now see a very simple web interface like this.

To get started with your first application click "Create Application" at the top. It will prompt you for a name. You will want to name it the same as whatever application you are going to deploy. In my case I'm going to deploy a sample .NET application first so I'm going to name it ".NET Demo".

After creating your application you should be presented with a screen like the following.

Currently, the values in the "GIT URL", "Application URL", and "Service URL" are kind of useless because they are not exposed to the internet. We're going to fix that right now. Leave the browser open to this page and hop back into IIS Manager. If you left it open then right-click "Sites" and select "Refresh"; Kudu added a couple new websites to IIS for us.

You should see two new websites. The first website is "kudu_net-demo" or "kudu_" followed by whatever name you chose. This website is the actual website that will host the files for your deployed application. The next website is "kudu_service_net-demo". This website is a Kudu service website that is dedicated to listening for Git deployments. It manages a local git repository, runs MSBUILD when you deploy your .NET application, etc.

To expose our app to the web we need to modify the IIS bindings for these websites. Let's start with the first one. Right-click "kudu_net-demo" (or whatever yours is called) and select "Edit Bindings...".

You will see a dialog pop open showing hostname/Port/IP bindings for this website.

Click the one binding that is already there and select "Edit...". Another dialog will pop open. Change the port to 80 and in the "Host name:" field put the domain for your web application.

NOTE: If you don't have a domain name yet, don't worry. I'll show you later how to trick your local computer into thinking you do. So use any domain name you wish, even if it's already taken on the web.

Click OK and then click "Add..." to create a second binding. Make it the same as the first one accept add "www." in front of it.

Click OK and close the bindings dialog for that website. Now open up the bindings dialog for the "kudu_service_net-demo" website. This website is only going to have one binding. Again change the port to 80 and modify the host name.

Before we map out hostnames to IP addresses we need to go back to the application pools again. This time you should see a new app pool with the same name as your application. In my case it is "net-demo". We are going to do the same thing to this app pool that we did to the Kudu Management one. Click "Advanced Settings...", navigate to "Identity", open up the dialog and change the account to "LocalSystem".

Once your app pool has been changed we also need to go enable basic authentication for the Kudu service website that was created for your website. Click on "kudu_service_net-demo" and select "Authentication". Disable anonymous authentication and enable basic authentication.

Now we can continue mapping our hostnames to our server IP. If you own the domains you used and know how to configure DNS for your domains then feel free to really point your domain at your server. You can find your virtual machine's public IP in the Windows Azure portal. That's the IP you'll need to point your domain to.

If you don't own the domain you used in your IIS bindings don't fret, you can map the domain to your server on your local machine. This domain will only work from the machine you set it up on, but that's good enough to test our app and make sure it works. We will set this up on both your local machine and the server. We have to set it up in your virtual machine for two reasons: first if you want to access your domain from within the virtual machine then you need to have the domain mapped there, and most importantly the Kudu Management page has to talk to the application it created and it will throw an error if it can't resolve the hostname.

To map your domain locally you need to open up notepad as administrator. Press the Windows key to open your start menu and begin typing "notepad" (this works on Windows 8 or 7). When notepad shows up right-click it and choose "Run as administrator".

Once you have an elevated notepad window open go to File > Open. Navigate to "C:\Windows\System32\Drivers\etc". Change the file type dropdown to "All Files (.)" in order to see the files in this directory.

Once you can see the files in the directory go ahead and open up "hosts". The contents of the file should look like the image below if you haven't modified it before.

All the lines in this file are currently commented out by preceding the line with a # character. If you are setting up the mapping on your virtual machine then add lines like this at the bottom of the file.

127.0.0.1    net-demo.com
127.0.0.1    www.net-demo.com
127.0.0.1    kudu.net-demo.com

If you didn't know, 127.0.0.1 is the address of the local machine. Since you are doing this mapping on the server you want to map the domain to the local IP address. You could technically use the virtual machine's public IP address if you want to. Next do the same thing on your local computer, except use the IP listed in the Windows Azure management portal.

Once you save your hosts file you should be able to open your browser and navigate to your website by going to the domain you specified. This works even if the domain really exists already because your machine looks at your hosts file to resolve hostnames before it reaches out to a real DNS server.

If you navigate to your domain you'll see a temporary html page that looks like this.

You should also be able to navigate directly to your Kudu Management Portal by putting your server's IP address into your browser's address bar. It will ask you for your credentials since we enabled basic authentication.

Click on your application. Notice that the values for GIT URL, Application URL, and Service URL have new values now. You can access these URLs from the web from your local machine, or from any machine if you mapped a real domain to your server.

Deploying Your Application

So far you've setup Kudu and created your first application within the Kudu management interface, but you've yet to deploy any code. Doing this is a lot easier than you might think. My first application is a .NET demo app so I'll create a default ASP.NET MVC application and deploy it. I installed Visual Studio Express 2012 for Web and I created a new MVC 4 project. Running the app locally looks like this.

To deploy this new application we simply have to initialize a local git repository. I've installed Git for Windows on my machine. To initialize my repository I CD'd into my project directory and ran the following.

git init

After initializing the repository you need to add all the files in your project to the repository and commit them.

git add .
git commit -m "Initial Commit."

Now we need to add your new Kudu service as a remote repository. You'll want to use the Git URL found in your Kudu Management portal, but with a little modification.

Because we enabled basic authentication on the Kudu service website we need to amend the git URL with our credentials.

http://<username>:<password>@kudu.net-demo.com/net-demo.git

To add this URL as a remote repository navigate to the directory of your project and run this command.

git remote add azure http://<username>:<password>@kudu.net-demo.com/net-demo.git

Once your remote repository is added we can finally push to it and trigger a deploy. Simply run the following command.

git push azure master

If successful, you should see output like this.

Now if you navigate to your domain you will see the fruits of your labor.

Pretty neat eh? A lot of up front work, yes, but going forward publishing changes to your app will be a breeze. But how about a Node.js application? To show you a working Node.js application deployment I am going to create another application within Kudu, perform all the required IIS modifications as before, and deploy the same way.

And the moment of truth?

What happened? For Node.js to work with IISNode we need to install another IIS extension called URL Rewrite. This is an extension that will allow IIS to route requests to varying URLs to your Node app. IISNode already sets up some rewrite rules in a Web.config file that it automatically adds when it deploys your Node app, so all we have to do is install the missing extension by heading over here.

This will install via the Microsoft Web Platform Installer, the same installer that helped us install Visual Studio Express 2012. Simply follow the install wizard until it finishes; there are no options to choose so just keep hitting next.

Once the URL Rewrite IIS extension is installed on the server go back to your local machine and refresh your page. You should see something like this.

Congratulations! You've setup your own virtual machine, installed and configured Kudu, and deployed both a .NET and a Node.js application successfully.