Java on Azure Websites – All about web.config configuration.

This post describes details of web.config to configure Java web applications on Azure Websites. If you have created a Java web application on Azure Websites and enabled Java using the Configuration UI as mentioned in this documentation – http://azure.microsoft.com/en-us/documentation/articles/web-sites-java-get-started/, you will not have a web.config. (If you create Java web application using the Application Gallery, you will already have web.config created for you).

The IIS module that manages the process creation and forwards requests is called HttpPlatformHandler. The section in web.config that configures HttpPlatformHandler is system.webServer\httpPlatform. A sample web.config to start a web application with default installation of Tomcat i.e the one installed in D:\Program Files(x86)\apache-tomcat-7.0.50 is:

<configuration>
  <system.webServer>
    <handlers>
      <add name="httpPlatformHandler" path="*"
           verb="*" modules="httpPlatformHandler"
           resourceType="Unspecified" />
    </handlers>

    <httpPlatform processPath="%AZURE_TOMCAT7_HOME%\bin\startup.bat">
    </httpPlatform>
  </system.webServer>
</configuration>

Having the above web.config in your site\wwwroot is exactly same as enabling Java and selecting Apache Tomcat 7.0.50 from the Azure websites portal configuration page. AZURE_TOMCAT7_HOME environment variable points to D:\Program Files (x86)\apache-tomcat-7.0.50 for convenience.

Now, lets say you want to set JAVA_OPTS, you can add that as environmentVariable in httpPlatform configuration.

<configuration>
  <system.webServer>
    <handlers>
      <add name="httpPlatformHandler" path="*"
           verb="*" modules="httpPlatformHandler"
           resourceType="Unspecified" />
    </handlers>

    <httpPlatform processPath="%AZURE_TOMCAT7_HOME%\bin\startup.bat">
      <environmentVariables>
        <environmentVariable name="JAVA_OPTS" value="-Djava.net.preferIPv4Stack=true -Duser.home=&quot;d:\home\site\wwwroot\user_home&quot;"/>
      </environmentVariables>
    </httpPlatform>
  </system.webServer>
</configuration>

So, now Tomcat will be started with the JAVA_OPTS you specified above. Refer to http://azure.microsoft.com/en-us/documentation/articles/web-sites-java-custom-upload/ to see how you can upload your own web container and configure it using web.config.

HttpPlatform Configuration in web.config:

HttpPlatform configuration has several attributes you can specify. Here is the full list:

processPath – path to the executable or script that will launch a process listening for Http requests.
examples:
1. %JAVA_HOME%\bin\java.exe
2. d:\home\site\wwwroot\bin\tomcat\bin\startup.bat
3. d:\home\site\wwwroot\bin\tomcat\bin\catalina.bat

arguments – (default=”") arguments to the executable or script specified in ‘processPath’ setting.
examples:
  1. processPath=”d:\home\site\wwwroot\bin\tomcat\bin\catalina.bat” arguments=”start”
  2. processPath=”%JAVA_HOME\bin\java.exe” arguments=”-Djava.net.preferIPv4Stack=true -Djetty.port=%HTTP_PLATFORM_PORT% -Djetty.base=&quot;d:\home\site\wwwroot\bin\jetty-distribution-9.1.0.v20131115&quot; -jar &quot;d:\home\site\wwwroot\bin\jetty-distribution-9.1.0.v20131115\start.jar&quot;”

startupTimeLimit – (default=10seconds) Duration for which HttpPlatformHandler will wait for the executable/script
to start a process listening on the port. If this time limit is exceeded, httpPlatformHandler will kill the process and try to launch it again ‘startupRetryCount’ times.

startupRetryCount – (default=10) Number of times HttpPlatformHandler will try to launch process specified in processPath. (please see startupTimeLimit for more details).

rapidFailsPerMinute – (default=10) Number of times the process specified in processPath is allowed to crash per minute. If this limit is exceeded, HttpPlatformHandler will stop launching the process for that minute.

requestTimeout – (default=”00:02:00″) Duration for which HttpPlatformHandler will wait for a response from the process listening on %HTTP_PLATFORM_PORT%.

stdoutLogEnabled – (default=”true”) stdout and stderr of the process specified in ‘processPath’ setting will be redirected to a file specified in ‘stdoutLogFile’ (see below).

stdoutLogFile – (default=’d:\home\LogFiles\httpPlatformStdout.txt’) absolute file path to the file where stdout/stderr from process
specified in processPath will be logged.

NOTE: %HTTP_PLATFORM_PORT% is a special placeholder which needs to specified either as part of ‘arguments’ or part of the httpPlatform ‘environmentVariable’ list – This will be replaced by an internally generated PORT by HttpPlatformHandler so that the process specified in ‘processPath’ setting can listen on this port.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>