Sat, 10 Dec 2011

Tutorial: Running the Mongoose Web Server in Windows Azure

[UPDATE 9/10/2012: Changed Windows Azure SDK location to match current versions.]

The Windows Azure SDK includes command-line tools that make it easy to deploy almost anything to the cloud. I’ve blogged about this functionality in the past, but those posts have assumed a significant amount of Windows Azure background. In this tutorial, I’ll walk through how to use those tools to package a standalone executable and run it in the cloud, assuming no prior Windows Azure experience. For our example application, we’ll run the Mongoose web server, a tiny one-file web server written in C++.

Prerequisites

To follow this tutorial, you’ll need to install the Windows Azure SDK. To complete the last step of deploying to the cloud, you’ll need a Windows Azure account. (Sign up at http://windowsazure.com.)

Quick Walkthrough

  1. Download the code at https://github.com/smarx/packanddeploy. You can either click the “zip” link at the top of the page, or you can use the git command-line tools:
    git clone git://github.com/smarx/packanddeploy .
  2. Run C:\Program Files\Microsoft SDKs\Windows Azure.NET SDK\<version>\bin\setenv.cmd to add the Windows Azure SDK tools to your path, and then change directory back to where you downloaded packanddeploy.
  3. Type run to run the application locally. Open up the browser to the address and port you see in the output of run. You should see the text “Hello, World!”
  4. Type pack to create a Windows Azure package containing the application.
  5. Browse to the Windows Azure portal and deploy the application by clicking the “new hosted service” button and filling out the dialog. The “package location” and “configuration file” should be PackAndDeploy.cspkg and ServiceConfiguration.Cloud.cscfg in the root of your packanddeploy project.

How it Works

Windows Azure applications consist of roles (essentially, components of the app). Roles come in two types: web and worker. Web roles are designed for hosting web applications under IIS. Worker roles are for everything else, with a simple “run forever” interface. This is what we’re using to run Mongoose.

Under the WorkerRole directory, you’ll see mongoose-3.0.exe, the Mongoose executable, and run.cmd, a batch file that launches Mongoose. run.cmd uses the following command to launch Mongoose:

start /w mongoose-3.0.exe -r . -p %ADDRESS%:%PORT% -e error_log.txt

ServiceDefinition.csdef in the root of the project defines the worker role to execute this batch file with the right environment variables:

<?xml version="1.0" encoding="utf-8"?>
<ServiceDefinition name="PackAndDeploy"
  xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceDefinition">
  <WorkerRole name="WorkerRole" vmsize="ExtraSmall">
    <Runtime>
      <Environment>
        <Variable name="ADDRESS">
           <RoleInstanceValue
             xpath="/RoleEnvironment/CurrentInstance/Endpoints/Endpoint[@name='HttpIn']/@address" />
        </Variable>
        <Variable name="PORT">
           <RoleInstanceValue
             xpath="/RoleEnvironment/CurrentInstance/Endpoints/Endpoint[@name='HttpIn']/@port" />
        </Variable>
      </Environment>
      <EntryPoint>
        <ProgramEntryPoint commandLine="run.cmd" setReadyOnProcessStart="true" />
      </EntryPoint>
    </Runtime>
    <Endpoints>
      <InputEndpoint name="HttpIn" protocol="tcp" port="80" />
    </Endpoints>
  </WorkerRole>
</ServiceDefinition>

This file does three main things:

  1. It defines the entry point to our application, which is run.cmd.
  2. It defines an endpoint for our application (port 80 for HTTP traffic).
  3. It configures two environment variables (ADDRESS and PORT) that communicate to our application what address and port it should listen on. (Windows Azure determines an address and port at runtime so that the application can work properly locally in the emulator as well as in the cloud.)

The run.cmd and pack.cmd commands take advantage of built-in tools in the SDK:

  • run.cmd invokes cspack with the /copyonly option to package up the application for local testing under the Windows Azure emulator. It then invokes csrun to launch the application locally.
  • pack.cmd invokes cspack again, this time without the /copyonly option, which packages the application for deployment to the cloud.

ServiceConfiguration.Local.cscfg and ServiceConfiguration.Cloud.cscfg configure the application for local testing and cloud deployment. The cloud version differs in that it configures the worker role to run on two instances (virtual machines) for high availability.

More Information

To learn more about the Windows Azure SDK authoring tools, see the documentation for cspack and csrun. To understand the various options for defining roles, see the reference documentation for ServiceDefiniton.csdef.

View the full source code for packanddeploy on GitHub: https://github.com/smarx/packanddeploy.

Translation: This article has been translated into Spanish by Maria Ramos from Webhostinghub.com/support/edu.