Announcing the Release of the HttpPlatformHandler Module for IIS 8+

We are delighted to announce the release of the HttpPlatformHandler module for IIS 8 and IIS 8.5.  The HttpPlatformHandler is used by Microsoft Azure Websites to host Java and now you can use the same module to host Java and other processes on local IIS installations.

The HttpPlatformHandler is an IIS Module which does the following two things:

1. Process Management of http listeners – this could be any process that can listen on a port for http requests.  For example – Tomcat, Jetty, Node.exe, Ruby etc;
2. Proxy requests to the process that it manages.

The HttpPlatformHandler enables these scenarios through a configuration section in your application’s web.config:

<configSchema>
  <sectionSchema name="system.webServer/httpPlatform">
    <attribute name="processPath" type="string" expanded="true"/>
    <attribute name="arguments" type="string" expanded="true" defaultValue=""/>
    <attribute name="startupTimeLimit" type="uint" defaultValue="10" validationType="integerRange" validationParameter="0,3600"/> <!-- in seconds -->
    <attribute name="startupRetryCount" type="uint" defaultValue="10" validationType="integerRange" validationParameter="0,100"/>
    <attribute name="rapidFailsPerMinute" type="uint" defaultValue="10" validationType="integerRange" validationParameter="0,100"/>
    <attribute name="requestTimeout" type="timeSpan" defaultValue="00:02:00" validationType="timeSpanRange" validationParameter="0,2592000,60"/>
    <attribute name="stdoutLogEnabled" type="bool" defaultValue="false" />
    <attribute name="stdoutLogFile" type="string" defaultValue="httpplatform-stdout" expanded="true"/>
    <attribute name="processesPerApplication" type="uint" defaultValue="1" validationType="integerRange" validationParameter="1,100"/>
    <element name="environmentVariables">
      <collection addElement="environmentVariable" clearElement="clear">
        <attribute name="name" type="string" required="true" validationType="nonEmptyString"/>
        <attribute name="value" type="string" required="true"/>
      </collection>
    </element>
  </sectionSchema>
</configSchema>

• Configuration Reference Article
• Download the HttpPlatformHandler

Hosting a Java Application in IIS using HttpPlatformHandler

In this example we will show how to host the Pebble Java blog engine on IIS using Tomcat and the HttpPlatformHandler.

1. Install the HttpPlatformHandler – WebPI/x86/x64
2. Download a copy of Tomcat from https://tomcat.apache.org/ and extract the zip to a folder on your machine, e.g. c:devjavasitesbinapache-tomcat-8.0.15
   
3. On the Tomcat side, there is one configuration change required.  The server.xml file (in conf folder) needs to be edited to set:
   • HTTP connector port=${port.http}
4. Download a copy of the Pebble blogging application (), or any other Java application you would like to use and put the war file in the webapps folder:
5. Now in IIS Manager – Add a New Website:
6. Complete the details as required setting the content directory physical path to the correct directory for your Java site and click ok.
7. Using a text editor of your choice create a new web.config file and add it to your website folder, i.e. c:devjavasitesweb.config
8. Edit the web.config file adding the httpPlatformHandler configuration as below
   • processPath – set to the patch to the location of startup.bat in your Tomcat folder
   • stdoutLogEnabled – set to True to enable logging
   • stoutLogFile – Path where to write the log file
   • EnvironmentVariables collection
     • JRE Home – Path to Java install on the machine
     • CATALINA_HOME – Path to Tomcat Folder
9. Browse to https://localhost/pebble and see the running application:

Additional Resources

• HttpPlatformHandler for IIS 8+ Download
• HttpPlatformHandler Configuration Reference
• Upload a custom Java Website to Azure Websites – Examples of how to configure the HttpPlatformHandler with Jetty, Hudson and Liferay
• HttpPlatformHandler Forum

Ref: edit the web.config file adding the httpPlatformHandler configuration:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="httpplatformhandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified"/>
    </handlers>
    <httpPlatform processPath="c:\dev\javasites\bin\apache-tomcat-8.0.15\bin\startup.bat" arguments="" stdoutLogEnabled="true" stdoutLogFile="\\?c:\dev\javasites\log.txt">
      <environmentVariables>
        <environmentVariable name="JRE_HOME" value="%programfiles%\java\jdk1.8.0_25" />
        <environmentVariable name="CATALINA_HOME" value="c:\dev\javasites\bin\apache-tomcat-8.0.15" />
      </environmentVariables>
    </httpPlatform>
  </system.webServer>
</configuration>