Custom Tomcat Configuration on Azure App Service Windows

App Service Windows includes multiple versions of Tomcat for your choosing & uses IIS to quickly update your process path once any new runtime version is pinned. Still, there are use cases where you may be looking to tweak the server configuration or completely modify the existing Tomcat installation that’s in use.

The platform maintains all avaliable runtimes within the read-only system drive therefore, the Web App can’t modify any installations in the C:\Program Files\.

To work around this with Tomcat, we’ll walk through modifying the IIS configuration with a web.config to either pass arguments to the current process path or update the path entirely.

See below to learn more about the App Service File System or the HttpPlatformHandler:

Azure File System Restrictions: https://github.com/projectkudu/kudu/wiki/Azure-Web-App-sandbox#file-system-restrictionsconsiderations

Understanding the Azure App Service File System: https://github.com/projectkudu/kudu/wiki/Understanding-the-Azure-App-Service-file-system

HttpPlatformHandler Configuration: https://docs.microsoft.com/en-us/iis/extensions/httpplatformhandler/httpplatformhandler-configuration-reference

Prerequisites

• Windows Web App running Tomcat
• Access to the SCM site(kudu)
• Tomcat Version Validated
  • Kudu > Process Explorer > Find Handle > “tomcat”

    

Custom server.xml Configuration

This method allows us to pass our custom configuration while still using the existing Tomcat Installation.

1. Navigate to the site directory from the Kudu site https://<sitename>.scm.azurewebsites.net/DebugConsole

2. Copy the read-only server.xml from the system drive to the site directory.

    //*Use your identifed tomcat version*
    copy "C:\Program Files\apache-tomcat-X.X.XX\conf\server.xml" \home\site
   

3. Create a web.config file inside C:\home\site\wwwroot with the configuration below.

    <?xml version="1.0" encoding="UTF-8"?>
    <configuration>
        <system.webServer>
            <handlers> 
                <remove name="httpPlatformHandlerMain" /> 
                <add name="httpPlatformHandlerMain" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified"/>
            </handlers> 
            <httpPlatform processPath="C:\Program Files\apache-tomcat-x.x.xx\bin\startup.bat" requestTimeout="00:04:00" arguments="-config C:\home\site\server.xml start" > 
                <environmentVariables> 
                </environmentVariables> 
            </httpPlatform>
        </system.webServer> 
    </configuration>
   

4. Request site from browser to confirm that the site is still avaliable with custom argument.

   If met with “The specified CGI application encountered an error and the server terminated the process.” Review the web.config for any errors. (invalid paths/arguments)

5. Modify the new server.xml & validate the changes!
   • I’ve modifed the default log path to confirm my changes using the line below. I should expect my logs to be saved in C:\home\site\Logfiles\test\RawLogs

     <Valve prefix="site_access_log.${catalina.instance.name}" pattern="%h %l %u %t &quot;%r&quot; %s %b %D %{x-arr-log-id}i" directory="${site.logdir}/test/RawLogs" className="org.apache.catalina.valves.AccessLogValve" suffix=".txt"/>

     

Custom Tomcat Configuration

This method allows for complete control over the Tomcat installation.

⚠️ Notice - When using a custom tomcat version, this is no longer maintained nor in sync with the App Service Platform if changes occur. (Configuration/Path-Mapping/Env Variables)

1. Navigate to the System drive for your tomcat directory from the Kudu site (i.e https://<sitename>.scm.azurewebsites.net/DebugConsole)

2. Download this from the system drive to your local machine.

   

3. Using Kudu, create a tomcat directory C:\home\site\tomcat Drag & drop the tomcat.zip to upload & unzip. (C:\home\site\tomcat)

   

4. Add a web.config within the wwwroot to point to new tomcat location

    <?xml version="1.0" encoding="UTF-8"?>
     <configuration>
     <system.webServer>
         <handlers>
         <remove name="httpPlatformHandlerMain" />
         <add name="httpPlatformHandlerMain" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified"/>
         </handlers>
         <httpPlatform processPath="C:\home\site\tomcat\bin\startup.bat" requestTimeout="00:04:00">
         <environmentVariables></environmentVariables>
         </httpPlatform>
     </system.webServer>
     </configuration>
   

5. Validate the new path tomcat handle path!