Use HttpPlatformHandler

Article
09/07/2016

Applies To: Windows Azure Pack

HttpPlatformHandler is an Internet Information Services (IIS) module that you can use to:

Manage any process (such as Tomcat, Jetty, node.exe, and Ruby) that can listen on a port for HTTP requests.
Send proxy requests to the process that it manages.

HttpPlatformHandler and Java web applications

The HttpPlatformHandler can be used with Windows Azure Pack: Web Sites to host Java and other processes.

You can deploy Java-based websites using FTP, Git, Kudu, and the integrated SCM capability for websites.

WebDeploy works as a protocol. Because Java is not developed in Visual Studio, WebDeploy does not fit with Java web application deployment use cases.

Configuration guidelines for custom Java web applications

Custom Java web applications on Azure require the following settings:

The HTTP port used by the Java process is dynamically assigned to the environment variable HTTP_PLATFORM_PORT. The HTTP listener must use this port.
All listener ports other than the single HTTP listener port must be disabled. In Tomcat, this includes the shutdown, HTTPS, and AJP ports.
The container must be configured for IPv4 traffic only.
The startup command for the application must be set in the configuration.
Applications that require writeable directories must be located in the content directory for Windows Azure Pack: Web Sites, which is D:\home. The environmental variable HOME refers to D:\home.

You can set environment variables in the Web.config file.

web.config httpPlatform configuration

The HttpPlatformHandler uses the following schema in your application’s Web.config file:

<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>

arguments (default = ""): The arguments sent to the HTTP listener identified by the processPath attribute.

Examples (shown with processPath included):

processPath="%HOME%\site\wwwroot\bin\tomcat\bin\catalina.bat"
arguments="start"

processPath="%JAVA_HOME\bin\java.exe"
arguments="-Djava.net.preferIPv4Stack=true -Djetty.port=%HTTP\_PLATFORM\_PORT% -Djetty.base=&quot;%HOME%\site\wwwroot\bin\jetty-distribution-9.1.0.v20131115&quot; -jar &quot;%HOME%\site\wwwroot\bin\jetty-distribution-9.1.0.v20131115\start.jar&quot;"

processPath: The path to the HTTP listener executable or script.

Examples:

processPath="%JAVA_HOME%\bin\java.exe"

processPath="%HOME%\site\wwwroot\bin\tomcat\bin\startup.bat"

processPath="%HOME%\site\wwwroot\bin\tomcat\bin\catalina.bat"

rapidFailsPerMinute (default = 10): The number of times per minute that the HTTP listener process is allowed to crash. If this limit is exceeded, HttpPlatformHandler will stop launching the process for the remainder of the minute.

requestTimeout (default = "00:02:00"): The amount of time HttpPlatformHandler will wait for a response from the process listening on %HTTP_PLATFORM_PORT%.

startupRetryCount (default = 10): The number of times HttpPlatformHandler will try to launch the HTTP listener process.

startupTimeLimit (default = 10 seconds): The amount of time HttpPlatformHandler will wait for the HTTP listener to start a process listening on the port. If this time limit is exceeded, HttpPlatformHandler will stop the HTTP listener and try to launch it again based on the value set for startupRetryCount.

stdoutLogEnabled (default = "true"): If True, stdout and stderr for the HTTP listener will be redirected to the file that is identified by stdoutLogFile.

stdoutLogFile (default="d:\home\LogFiles\httpPlatformStdout.log"): The absolute file path to log stdout and stderr from the HTTP listener.

Note

%HTTP_PLATFORM_PORT% is a special placeholder that must be specified as part of the arguments attribute or the httpPlatformEnvironmentVariables list. HttpPlatformHandler dynamically replaces this variable with a port so that the HTTP listener can listen on this port.

Application configuration examples

For the following Tomcat and Jetty examples, sample Web.config files and application configurations show how to enable your Java application on Windows Azure Pack: Web Sites.

Tomcat

The following example shows an installation of Tomcat on a Java virtual machine:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="httpPlatformHandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified" />
    </handlers>
    <httpPlatform processPath="%HOME%\site\wwwroot\bin\tomcat\bin\startup.bat" 
        arguments="">
      <environmentVariables>
        <environmentVariable name="CATALINA_OPTS" value="-Dport.http=%HTTP_PLATFORM_PORT%" />
        <environmentVariable name="CATALINA_HOME" value="%HOME%\site\wwwroot\bin\tomcat" />
        <environmentVariable name="JRE_HOME" value="%HOME%\site\wwwroot\bin\java" /> <!-- optional, if not specified, this will default to %programfiles%\Java -->
        <environmentVariable name="JAVA_OPTS" value="-Djava.net.preferIPv4Stack=true" />
      </environmentVariables>
    </httpPlatform>
  </system.webServer>
</configuration>

You must also make Tomcat configuration changes. The settings for the server xml need to be edited as follows:

Shutdown port = -1
HTTP connector port = ${port.http}
HTTP connector address = "127.0.0.1"
Comment out HTTPS and AJP connectors

The IPv4 setting can also be set in the catalina.properties file, where you can add java.net.preferIPv4Stack=true.

Direct3D calls are not supported on Windows Azure Pack: Web Sites. If your application makes such calls, disable them by adding the following Java option: -Dsun.java2d.d3d=false.

Jetty

An example configuration to run a full installation of Jetty:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="httppPlatformHandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified" />
    </handlers>
    <httpPlatform processPath="%JAVA_HOME%\bin\java.exe" 
         arguments="-Djava.net.preferIPv4Stack=true -Djetty.port=%HTTP_PLATFORM_PORT% -Djetty.base=&quot;%HOME%\site\wwwroot\bin\jetty-distribution-9.1.0.v20131115&quot; -jar &quot;%HOME%\site\wwwroot\bin\jetty-distribution-9.1.0.v20131115\start.jar&quot;"
        startupTimeLimit="20"
      startupRetryCount="10"
      stdoutLogEnabled="true">
    </httpPlatform>
  </system.webServer>
</configuration>

The Jetty configuration must be changed in the start INI file as follows: java.net.preferIPv4Stack=true.

Host a Java application by using HttpPlatformHandler

To host a Java application by using HttpPlaftormHandler, follow these steps:

Create an empty website by using the management portal for tenants.
Download a copy of Tomcat (for example, from http://tomcat.apache.org/), and extract the zip file to a folder on a development computer (for example: c:\dev\javasites\bin\apache-tomcat-8.0.15).
Add a copy of the Java Development Kit to the folder with Tomcat (for example: c:\dev\javasites\bin\jdk1.7.0_79).
Make the changes to the Tomcat configuration as explained in the Tomcat example above.
Download a copy of the Java application that you want to use (for example, the Pebble blogging tool) to the webapps folder.
Use a text editor to create a new Web.config file and add it to your website folder (for example: c:\dev\javasites\web.config).

Edit the Web.config file to add the HttpPlatformHandler configuration as follows. This configuration specifies the location of the Tomcat server and the JDK directory, sets up Catalina, and defines the ${user.home} variable that is needed by Pebble:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <handlers>
            <add name="httpplatformhandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified" />
        </handlers>

        <httpPlatform processPath="%HOME%\site\wwwroot\bin\apache-tomcat-8.0.15\bin\startup.bat" 
                      arguments="">
            <environmentVariables>
                <environmentVariable name="JRE_HOME" value="%HOME%\site\wwwroot\bin\jdk1.7.0_79" />
                <environmentVariable name="CATALINA_OPTS" value="-Dport.http=%HTTP_PLATFORM_PORT% -Dsomeotherconfig=value" />
                <environmentVariable name="CATALINA_HOME" value="%HOME%\site\wwwroot\bin\apache-tomcat-8.0.15" />
  <environmentVariable name="JAVA_OPTS" value="-Duser.home=%HOME%/site/wwwroot/user_home"/>
            </environmentVariables>
        </httpPlatform>
    </system.webServer>
</configuration>

Upload the contents of c:\dev\javasites to the wwwroot folder of the website that you created in Step 1.
To browse to the Pebble Java application, append /pebble to the root URL (for example, http://javawebsite.awbl-s.redant.selfhost.corp.microsoft.com/pebble/).