Configure a Java app for Azure App Service

To show the current Java version, run the following command in the Cloud Shell:

az webapp config show --name <app-name> --resource-group <resource-group-name> --query "[javaVersion, javaContainer, javaContainerVersion]"

To show all supported Java versions, run the following command in the Cloud Shell:

az webapp list-runtimes --os windows | grep java

To show the current Java version, run the following command in the Cloud Shell:

az webapp config show --resource-group <resource-group-name> --name <app-name> --query linuxFxVersion

To show all supported Java versions, run the following command in the Cloud Shell:

az webapp list-runtimes --os linux | grep "JAVA\|TOMCAT\|JBOSSEAP"

JBoss EAP

To deploy .war files to JBoss, use the /api/wardeploy/ endpoint to POST your archive file. For more information on this API, see this documentation.

To deploy .ear files, use FTP. Your .ear application is deployed to the context root defined in your application's configuration. For example, if the context root of your app is <context-root>myapp</context-root>, then you can browse the site at the /myapp path: http://my-app-name.azurewebsites.net/myapp. If you want your web app to be served in the root path, ensure that your app sets the context root to the root path: <context-root>/</context-root>. For more information, see Setting the context root of a web application.

To access the console logs generated from inside your application code in App Service, turn on diagnostics logging by running the following command in the Cloud Shell:

az webapp log config --resource-group <resource-group-name> --name <app-name> --docker-container-logging filesystem --level Verbose

Possible values for --level are: Error, Warning, Info, and Verbose. Each subsequent level includes the previous level. For example: Error includes only error messages, and Verbose includes all messages.

Once diagnostic logging is turned on, run the following command to see the log stream:

az webapp log tail --resource-group <resource-group-name> --name <app-name>

If you don't see console logs immediately, check again in 30 seconds.

To stop log streaming at any time, type Ctrl+C.

You can access the console logs generated from inside the container.

First, turn on container logging by running the following command:

az webapp log config --name <app-name> --resource-group <resource-group-name> --docker-container-logging filesystem

Replace <app-name> and <resource-group-name> with the names appropriate for your web app.

Once container logging is turned on, run the following command to see the log stream:

az webapp log tail --name <app-name> --resource-group <resource-group-name>

If you don't see console logs immediately, check again in 30 seconds.

To stop log streaming at any time, type Ctrl+C.

You can also inspect the log files in a browser at https://<app-name>.scm.azurewebsites.net/api/logs/docker.

SSH console access

To make open a direct SSH session with your container, your app should be running.

Paste the following URL into your browser and replace <app-name> with your app name:

https://<app-name>.scm.azurewebsites.net/webssh/host

If you're not yet authenticated, you're required to authenticate with your Azure subscription to connect. Once authenticated, you see an in-browser shell, where you can run commands inside your container.

To open a remote SSH session from your local machine, see Open SSH session from remote shell.

Troubleshooting tools

The built-in Java images are based on the Alpine Linux operating system. Use the apk package manager to install any troubleshooting tools or commands.

Timed Recording

To take a timed recording, you need the PID (Process ID) of the Java application. To find the PID, open a browser to your web app's SCM site at https://<your-site-name>.scm.azurewebsites.net/ProcessExplorer/. This page shows the running processes in your web app. Find the process named "java" in the table and copy the corresponding PID (Process ID).

Next, open the Debug Console in the top toolbar of the SCM site and run the following command. Replace <pid> with the process ID you copied earlier. This command starts a 30-second profiler recording of your Java application and generate a file named timed_recording_example.jfr in the C:\home directory.

jcmd <pid> JFR.start name=TimedRecording settings=profile duration=30s filename="C:\home\timed_recording_example.JFR"

SSH into your App Service and run the jcmd command to see a list of all the Java processes running. In addition to jcmd itself, you should see your Java application running with a process ID number (pid).

078990bbcd11:/home# jcmd
Picked up JAVA_TOOL_OPTIONS: -Djava.net.preferIPv4Stack=true
147 sun.tools.jcmd.JCmd
116 /home/site/wwwroot/app.jar

Execute the following command to start a 30-second recording of the JVM. It profiles the JVM and creates a JFR file named jfr_example.jfr in the home directory. (Replace 116 with the pid of your Java app.)

jcmd 116 JFR.start name=MyRecording settings=profile duration=30s filename="/home/jfr_example.jfr"

During the 30-second interval, you can validate the recording is taking place by running jcmd 116 JFR.check. The command shows all recordings for the given Java process.

Continuous Recording

You can use Java Flight Recorder to continuously profile your Java application with minimal impact on runtime performance. To do so, run the following Azure CLI command to create an App Setting named JAVA_OPTS with the necessary configuration. The contents of the JAVA_OPTS App Setting are passed to the java command when your app is started.

az webapp config appsettings set -g <your_resource_group> -n <your_app_name> --settings JAVA_OPTS=-XX:StartFlightRecording=disk=true,name=continuous_recording,dumponexit=true,maxsize=1024m,maxage=1d

Once the recording starts, you can dump the current recording data at any time using the JFR.dump command.

jcmd <pid> JFR.dump name=continuous_recording filename="/home/recording1.jfr"

Enable application logging through the Azure portal or Azure CLI to configure App Service to write your application's standard console output and standard console error streams to the local filesystem or Azure Blob Storage. Logging to the local App Service filesystem instance is disabled 12 hours after it's configured. If you need longer retention, configure the application to write output to a Blob storage container. Your Java and Tomcat app logs can be found in the /home/LogFiles/Application/ directory.

Enable application logging through the Azure portal or Azure CLI to configure App Service to write your application's standard console output and standard console error streams to the local filesystem or Azure Blob Storage. If you need longer retention, configure the application to write output to a Blob storage container. Your Java and Tomcat app logs can be found in the /home/LogFiles/Application/ directory.

Azure Blob Storage logging for Linux based apps can only be configured using Azure Monitor.

Use the Java Key Store

By default, any public or private certificates uploaded to App Service Linux are loaded into the respective Java Key Stores as the container starts. After uploading your certificate, you'll need to restart your App Service for it to be loaded into the Java Key Store. Public certificates are loaded into the Key Store at $JRE_HOME/lib/security/cacerts, and private certificates are stored in $JRE_HOME/lib/security/client.jks.

More configuration might be necessary for encrypting your JDBC connection with certificates in the Java Key Store. Refer to the documentation for your chosen JDBC driver.

• PostgreSQL
• SQL Server
• MongoDB
• Cassandra

Initialize the Java Key Store

To initialize the import java.security.KeyStore object, load the keystore file with the password. The default password for both key stores is changeit.

KeyStore keyStore = KeyStore.getInstance("jks");
keyStore.load(
    new FileInputStream(System.getenv("JRE_HOME")+"/lib/security/cacerts"),
    "changeit".toCharArray());

KeyStore keyStore = KeyStore.getInstance("pkcs12");
keyStore.load(
    new FileInputStream(System.getenv("JRE_HOME")+"/lib/security/client.jks"),
    "changeit".toCharArray());

Manually load the key store

You can load certificates manually to the key store. Create an app setting, SKIP_JAVA_KEYSTORE_LOAD, with a value of 1 to disable App Service from loading the certificates into the key store automatically. All public certificates uploaded to App Service via the Azure portal are stored under /var/ssl/certs/. Private certificates are stored under /var/ssl/private/.

You can interact or debug the Java Key Tool by opening an SSH connection to your App Service and running the command keytool. See the Key Tool documentation for a list of commands. For more information on the KeyStore API, see the official documentation.

3. Set the instrumentation key, connection string, and monitoring agent version as app settings on the web app. Replace <instrumentationKey> and <connectionString> with the values from the previous step.

   az webapp config appsettings set -n <webapp-name> -g <resource-group> --settings "APPINSIGHTS_INSTRUMENTATIONKEY=<instrumentationKey>" "APPLICATIONINSIGHTS_CONNECTION_STRING=<connectionString>" "ApplicationInsightsAgent_EXTENSION_VERSION=~3" "XDT_MicrosoftApplicationInsights_Mode=default" "XDT_MicrosoftApplicationInsights_Java=1"
   

3. Set the instrumentation key, connection string, and monitoring agent version as app settings on the web app. Replace <instrumentationKey> and <connectionString> with the values from the previous step.

   az webapp config appsettings set -n <webapp-name> -g <resource-group> --settings "APPINSIGHTS_INSTRUMENTATIONKEY=<instrumentationKey>" "APPLICATIONINSIGHTS_CONNECTION_STRING=<connectionString>" "ApplicationInsightsAgent_EXTENSION_VERSION=~3" "XDT_MicrosoftApplicationInsights_Mode=default"
   

1. Create a NewRelic account at NewRelic.com

2. Download the Java agent from NewRelic. It has a file name similar to newrelic-java-x.x.x.zip.

3. Copy your license key, you need it to configure the agent later.

4. SSH into your App Service instance and create a new directory /home/site/wwwroot/apm.

5. Upload the unpacked NewRelic Java agent files into a directory under /home/site/wwwroot/apm. The files for your agent should be in /home/site/wwwroot/apm/newrelic.

6. Modify the YAML file at /home/site/wwwroot/apm/newrelic/newrelic.yml and replace the placeholder license value with your own license key.

7. In the Azure portal, browse to your application in App Service and create a new Application Setting.

   • For Java SE apps, create an environment variable named JAVA_OPTS with the value -javaagent:/home/site/wwwroot/apm/newrelic/newrelic.jar.
   • For Tomcat, create an environment variable named CATALINA_OPTS with the value -javaagent:/home/site/wwwroot/apm/newrelic/newrelic.jar.

1. Create a NewRelic account at NewRelic.com

2. Download the Java agent from NewRelic. It has a file name similar to newrelic-java-x.x.x.zip.

3. Copy your license key, you'll need it to configure the agent later.

4. SSH into your App Service instance and create a new directory /home/site/wwwroot/apm.

5. Upload the unpacked NewRelic Java agent files into a directory under /home/site/wwwroot/apm. The files for your agent should be in /home/site/wwwroot/apm/newrelic.

6. Modify the YAML file at /home/site/wwwroot/apm/newrelic/newrelic.yml and replace the placeholder license value with your own license key.

7. In the Azure portal, browse to your application in App Service and create a new Application Setting.

   • For Java SE apps, create an environment variable named JAVA_OPTS with the value -javaagent:/home/site/wwwroot/apm/newrelic/newrelic.jar.
   • For Tomcat, create an environment variable named CATALINA_OPTS with the value -javaagent:/home/site/wwwroot/apm/newrelic/newrelic.jar.

1. Create an AppDynamics account at AppDynamics.com

2. Download the Java agent from the AppDynamics website. The file name is similar to AppServerAgent-x.x.x.xxxxx.zip

3. Use the Kudu console to create a new directory /home/site/wwwroot/apm.

4. Upload the Java agent files into a directory under /home/site/wwwroot/apm. The files for your agent should be in /home/site/wwwroot/apm/appdynamics.

5. In the Azure portal, browse to your application in App Service and create a new Application Setting.

   • For Java SE apps, create an environment variable named JAVA_OPTS with the value -javaagent:/home/site/wwwroot/apm/appdynamics/javaagent.jar -Dappdynamics.agent.applicationName=<app-name> where <app-name> is your App Service name.
   • For Tomcat apps, create an environment variable named CATALINA_OPTS with the value -javaagent:/home/site/wwwroot/apm/appdynamics/javaagent.jar -Dappdynamics.agent.applicationName=<app-name> where <app-name> is your App Service name.

1. Create an AppDynamics account at AppDynamics.com

2. Download the Java agent from the AppDynamics website. The file name is similar to AppServerAgent-x.x.x.xxxxx.zip

3. SSH into your App Service instance and create a new directory /home/site/wwwroot/apm.

4. Upload the Java agent files into a directory under /home/site/wwwroot/apm. The files for your agent should be in /home/site/wwwroot/apm/appdynamics.

5. In the Azure portal, browse to your application in App Service and create a new Application Setting.

   • For Java SE apps, create an environment variable named JAVA_OPTS with the value -javaagent:/home/site/wwwroot/apm/appdynamics/javaagent.jar -Dappdynamics.agent.applicationName=<app-name> where <app-name> is your App Service name.
   • For Tomcat apps, create an environment variable named CATALINA_OPTS with the value -javaagent:/home/site/wwwroot/apm/appdynamics/javaagent.jar -Dappdynamics.agent.applicationName=<app-name> where <app-name> is your App Service name.

Tomcat

These instructions apply to all database connections. You need to fill placeholders with your chosen database's driver class name and JAR file. Provided is a table with class names and driver downloads for common databases.

To configure Tomcat to use Java Database Connectivity (JDBC) or the Java Persistence API (JPA), first customize the CATALINA_OPTS environment variable that is read in by Tomcat at start-up. Set these values through an app setting in the App Service Maven plugin:

<appSettings>
    <property>
        <name>CATALINA_OPTS</name>
        <value>"$CATALINA_OPTS -Ddbuser=${DBUSER} -Ddbpassword=${DBPASSWORD} -DconnURL=${CONNURL}"</value>
    </property>
</appSettings>

Or set the environment variables in the Configuration > Application Settings page in the Azure portal.

Next, determine if the data source should be available to one application or to all applications running on the Tomcat servlet.

Application-level data sources

1. Create a context.xml file in the META-INF/ directory of your project. Create the META-INF/ directory if it doesn't exist.

2. In context.xml, add a Context element to link the data source to a JNDI address. Replace the driverClassName placeholder with your driver's class name from the table above.

   <Context>
       <Resource
           name="jdbc/dbconnection"
           type="javax.sql.DataSource"
           url="${connURL}"
           driverClassName="<insert your driver class name>"
           username="${dbuser}"
           password="${dbpassword}"
       />
   </Context>
   

3. Update your application's web.xml to use the data source in your application.

   <resource-env-ref>
       <resource-env-ref-name>jdbc/dbconnection</resource-env-ref-name>
       <resource-env-ref-type>javax.sql.DataSource</resource-env-ref-type>
   </resource-env-ref>
   

Shared server-level resources

Tomcat installations on App Service on Windows exist in shared space on the App Service Plan. You can't directly modify a Tomcat installation for server-wide configuration. To make server-level configuration changes to your Tomcat installation, you must copy Tomcat to a local folder, in which you can modify Tomcat's configuration.

Automate creating custom Tomcat on app start

You can use a startup script to perform actions before a web app starts. The startup script for customizing Tomcat needs to complete the following steps:

1. Check whether Tomcat was already copied and configured locally. If it was, the startup script can end here.
2. Copy Tomcat locally.
3. Make the required configuration changes.
4. Indicate that configuration was successfully completed.

For Windows apps, create a file named startup.cmd or startup.ps1 in the wwwroot directory. This file runs automatically before the Tomcat server starts.

Here's a PowerShell script that completes these steps:

    # Check for marker file indicating that config has already been done
    if(Test-Path "$Env:LOCAL_EXPANDED\tomcat\config_done_marker"){
        return 0
    }

    # Delete previous Tomcat directory if it exists
    # In case previous config isn't completed or a new config should be forcefully installed
    if(Test-Path "$Env:LOCAL_EXPANDED\tomcat"){
        Remove-Item "$Env:LOCAL_EXPANDED\tomcat" -Recurse
    }

    # Copy Tomcat to local
    # Using the environment variable $AZURE_TOMCAT90_HOME uses the 'default' version of Tomcat
    New-Item "$Env:LOCAL_EXPANDED\tomcat" -ItemType Directory
    Copy-Item -Path "$Env:AZURE_TOMCAT90_HOME\*" -Destination "$Env:LOCAL_EXPANDED\tomcat" -Recurse

    # Perform the required customization of Tomcat
    {... customization ...}

    # Mark that the operation was a success
    New-Item -Path "$Env:LOCAL_EXPANDED\tomcat\config_done_marker" -ItemType File

Transforms

A common use case for customizing a Tomcat version is to modify the server.xml, context.xml, or web.xml Tomcat configuration files. App Service already modifies these files to provide platform features. To continue to use these features, it's important to preserve the content of these files when you make changes to them. To accomplish this, we recommend that you use an XSL transformation (XSLT). Use an XSL transform to make changes to the XML files while preserving the original contents of the file.

Example XSLT file

This example transform adds a new connector node to server.xml. Note the Identity Transform, which preserves the original contents of the file.

    <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    <xsl:output method="xml" indent="yes"/>

    <!-- Identity transform: this ensures that the original contents of the file are included in the new file -->
    <!-- Ensure that your transform files include this block -->
    <xsl:template match="@* | node()" name="Copy">
      <xsl:copy>
        <xsl:apply-templates select="@* | node()"/>
      </xsl:copy>
    </xsl:template>

    <xsl:template match="@* | node()" mode="insertConnector">
      <xsl:call-template name="Copy" />
    </xsl:template>

    <xsl:template match="comment()[not(../Connector[@scheme = 'https']) and
                                   contains(., '&lt;Connector') and
                                   (contains(., 'scheme=&quot;https&quot;') or
                                    contains(., &quot;scheme='https'&quot;))]">
      <xsl:value-of select="." disable-output-escaping="yes" />
    </xsl:template>

    <xsl:template match="Service[not(Connector[@scheme = 'https'] or
                                     comment()[contains(., '&lt;Connector') and
                                               (contains(., 'scheme=&quot;https&quot;') or
                                                contains(., &quot;scheme='https'&quot;))]
                                    )]
                        ">
      <xsl:copy>
        <xsl:apply-templates select="@* | node()" mode="insertConnector" />
      </xsl:copy>
    </xsl:template>

    <!-- Add the new connector after the last existing Connnector if there's one -->
    <xsl:template match="Connector[last()]" mode="insertConnector">
      <xsl:call-template name="Copy" />

      <xsl:call-template name="AddConnector" />
    </xsl:template>

    <!-- ... or before the first Engine if there's no existing Connector -->
    <xsl:template match="Engine[1][not(preceding-sibling::Connector)]"
                  mode="insertConnector">
      <xsl:call-template name="AddConnector" />

      <xsl:call-template name="Copy" />
    </xsl:template>

    <xsl:template name="AddConnector">
      <!-- Add new line -->
      <xsl:text>&#xa;</xsl:text>
      <!-- This is the new connector -->
      <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" 
                 maxThreads="150" scheme="https" secure="true" 
                 keystoreFile="${{user.home}}/.keystore" keystorePass="changeit"
                 clientAuth="false" sslProtocol="TLS" />
    </xsl:template>

    </xsl:stylesheet>

Function for XSL transform

PowerShell has built-in tools for transforming XML files by using XSL transforms. The following script is an example function that you can use in startup.ps1 to perform the transform:

    function TransformXML{
        param ($xml, $xsl, $output)

        if (-not $xml -or -not $xsl -or -not $output)
        {
            return 0
        }

        Try
        {
            $xslt_settings = New-Object System.Xml.Xsl.XsltSettings;
            $XmlUrlResolver = New-Object System.Xml.XmlUrlResolver;
            $xslt_settings.EnableScript = 1;

            $xslt = New-Object System.Xml.Xsl.XslCompiledTransform;
            $xslt.Load($xsl,$xslt_settings,$XmlUrlResolver);
            $xslt.Transform($xml, $output);

        }

        Catch
        {
            $ErrorMessage = $_.Exception.Message
            $FailedItem = $_.Exception.ItemName
            Write-Host  'Error'$ErrorMessage':'$FailedItem':' $_.Exception;
            return 0
        }
        return 1
    }

App settings

The platform also needs to know where your custom version of Tomcat is installed. You can set the installation's location in the CATALINA_BASE app setting.

You can use the Azure CLI to change this setting:

    az webapp config appsettings set -g $MyResourceGroup -n $MyUniqueApp --settings CATALINA_BASE="%LOCAL_EXPANDED%\tomcat"

Or, you can manually change the setting in the Azure portal:

1. Go to Settings > Configuration > Application settings.
2. Select New Application Setting.
3. Use these values to create the setting:
   1. Name: CATALINA_BASE
   2. Value: "%LOCAL_EXPANDED%\tomcat"

Example startup.ps1

The following example script copies a custom Tomcat to a local folder, performs an XSL transform, and indicates that the transform was successful:

    # Locations of xml and xsl files
    $target_xml="$Env:LOCAL_EXPANDED\tomcat\conf\server.xml"
    $target_xsl="$Env:HOME\site\server.xsl"

    # Define the transform function
    # Useful if transforming multiple files
    function TransformXML{
        param ($xml, $xsl, $output)

        if (-not $xml -or -not $xsl -or -not $output)
        {
            return 0
        }

        Try
        {
            $xslt_settings = New-Object System.Xml.Xsl.XsltSettings;
            $XmlUrlResolver = New-Object System.Xml.XmlUrlResolver;
            $xslt_settings.EnableScript = 1;

            $xslt = New-Object System.Xml.Xsl.XslCompiledTransform;
            $xslt.Load($xsl,$xslt_settings,$XmlUrlResolver);
            $xslt.Transform($xml, $output);
        }

        Catch
        {
            $ErrorMessage = $_.Exception.Message
            $FailedItem = $_.Exception.ItemName
            echo  'Error'$ErrorMessage':'$FailedItem':' $_.Exception;
            return 0
        }
        return 1
    }

    $success = TransformXML -xml $target_xml -xsl $target_xsl -output $target_xml

    # Check for marker file indicating that config has already been done
    if(Test-Path "$Env:LOCAL_EXPANDED\tomcat\config_done_marker"){
        return 0
    }

    # Delete previous Tomcat directory if it exists
    # In case previous config isn't completed or a new config should be forcefully installed
    if(Test-Path "$Env:LOCAL_EXPANDED\tomcat"){
        Remove-Item "$Env:LOCAL_EXPANDED\tomcat" --recurse
    }

    md -Path "$Env:LOCAL_EXPANDED\tomcat"

    # Copy Tomcat to local
    # Using the environment variable $AZURE_TOMCAT90_HOME uses the 'default' version of Tomcat
    Copy-Item -Path "$Env:AZURE_TOMCAT90_HOME\*" "$Env:LOCAL_EXPANDED\tomcat" -Recurse

    # Perform the required customization of Tomcat
    $success = TransformXML -xml $target_xml -xsl $target_xsl -output $target_xml

    # Mark that the operation was a success if successful
    if($success){
        New-Item -Path "$Env:LOCAL_EXPANDED\tomcat\config_done_marker" -ItemType File
    }

Finalize configuration

Finally, you place the driver JARs in the Tomcat classpath and restart your App Service. Ensure that the JDBC driver files are available to the Tomcat classloader by placing them in the /home/site/lib directory. In the Cloud Shell, run az webapp deploy --type=lib for each driver JAR:

az webapp deploy --resource-group <group-name> --name <app-name> --src-path <jar-name>.jar --type=lib --target-path <jar-name>.jar

Tomcat

These instructions apply to all database connections. You need to fill placeholders with your chosen database's driver class name and JAR file. Provided is a table with class names and driver downloads for common databases.

To configure Tomcat to use Java Database Connectivity (JDBC) or the Java Persistence API (JPA), first customize the CATALINA_OPTS environment variable that is read in by Tomcat at start-up. Set these values through an app setting in the App Service Maven plugin:

<appSettings>
    <property>
        <name>CATALINA_OPTS</name>
        <value>"$CATALINA_OPTS -Ddbuser=${DBUSER} -Ddbpassword=${DBPASSWORD} -DconnURL=${CONNURL}"</value>
    </property>
</appSettings>

Or set the environment variables in the Configuration > Application Settings page in the Azure portal.

Next, determine if the data source should be available to one application or to all applications running on the Tomcat servlet.

Application-level data sources

1. Create a context.xml file in the META-INF/ directory of your project. Create the META-INF/ directory if it doesn't exist.

2. In context.xml, add a Context element to link the data source to a JNDI address. Replace the driverClassName placeholder with your driver's class name from the table above.

   <Context>
       <Resource
           name="jdbc/dbconnection"
           type="javax.sql.DataSource"
           url="${connURL}"
           driverClassName="<insert your driver class name>"
           username="${dbuser}"
           password="${dbpassword}"
       />
   </Context>
   

3. Update your application's web.xml to use the data source in your application.

   <resource-env-ref>
       <resource-env-ref-name>jdbc/dbconnection</resource-env-ref-name>
       <resource-env-ref-type>javax.sql.DataSource</resource-env-ref-type>
   </resource-env-ref>
   

Shared server-level resources

Adding a shared, server-level data source requires you to edit Tomcat's server.xml. First, upload a startup script and set the path to the script in Configuration > Startup Command. You can upload the startup script using FTP.

Your startup script will make an xsl transform to the server.xml file and output the resulting xml file to /usr/local/tomcat/conf/server.xml. The startup script should install libxslt via apk. Your xsl file and startup script can be uploaded via FTP. Below is an example startup script.

# Install libxslt. Also copy the transform file to /home/tomcat/conf/
apk add --update libxslt

# Usage: xsltproc --output output.xml style.xsl input.xml
xsltproc --output /home/tomcat/conf/server.xml /home/tomcat/conf/transform.xsl /usr/local/tomcat/conf/server.xml

The following example XSL file adds a new connector node to the Tomcat server.xml.

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="xml" indent="yes"/>

  <xsl:template match="@* | node()" name="Copy">
    <xsl:copy>
      <xsl:apply-templates select="@* | node()"/>
    </xsl:copy>
  </xsl:template>

  <xsl:template match="@* | node()" mode="insertConnector">
    <xsl:call-template name="Copy" />
  </xsl:template>

  <xsl:template match="comment()[not(../Connector[@scheme = 'https']) and
                                 contains(., '&lt;Connector') and
                                 (contains(., 'scheme=&quot;https&quot;') or
                                  contains(., &quot;scheme='https'&quot;))]">
    <xsl:value-of select="." disable-output-escaping="yes" />
  </xsl:template>

  <xsl:template match="Service[not(Connector[@scheme = 'https'] or
                                   comment()[contains(., '&lt;Connector') and
                                             (contains(., 'scheme=&quot;https&quot;') or
                                              contains(., &quot;scheme='https'&quot;))]
                                  )]
                      ">
    <xsl:copy>
      <xsl:apply-templates select="@* | node()" mode="insertConnector" />
    </xsl:copy>
  </xsl:template>

  <!-- Add the new connector after the last existing Connnector if there's one -->
  <xsl:template match="Connector[last()]" mode="insertConnector">
    <xsl:call-template name="Copy" />

    <xsl:call-template name="AddConnector" />
  </xsl:template>

  <!-- ... or before the first Engine if there's no existing Connector -->
  <xsl:template match="Engine[1][not(preceding-sibling::Connector)]"
                mode="insertConnector">
    <xsl:call-template name="AddConnector" />

    <xsl:call-template name="Copy" />
  </xsl:template>

  <xsl:template name="AddConnector">
    <!-- Add new line -->
    <xsl:text>&#xa;</xsl:text>
    <!-- This is the new connector -->
    <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" 
               maxThreads="150" scheme="https" secure="true" 
               keystoreFile="${{user.home}}/.keystore" keystorePass="changeit"
               clientAuth="false" sslProtocol="TLS" />
  </xsl:template>

</xsl:stylesheet>

Finalize configuration

Finally, place the driver JARs in the Tomcat classpath and restart your App Service.

1. Ensure that the JDBC driver files are available to the Tomcat classloader by placing them in the /home/site/lib directory. In the Cloud Shell, run az webapp deploy --type=lib for each driver JAR:

az webapp deploy --resource-group <group-name> --name <app-name> --src-path <jar-name>.jar --type=lib --path <jar-name>.jar

If you created a server-level data source, restart the App Service Linux application. Tomcat will reset CATALINA_BASE to /home/tomcat and use the updated configuration.

JBoss EAP Data Sources

There are three core steps when registering a data source with JBoss EAP: uploading the JDBC driver, adding the JDBC driver as a module, and registering the module. App Service is a stateless hosting service, so the configuration commands for adding and registering the data source module must be scripted and applied as the container starts.

1. Obtain your database's JDBC driver.

2. Create an XML module definition file for the JDBC driver. The following example shows a module definition for PostgreSQL.

   <?xml version="1.0" ?>
   <module xmlns="urn:jboss:module:1.1" name="org.postgres">
       <resources>
       <!-- ***** IMPORTANT : REPLACE THIS PLACEHOLDER *******-->
       <resource-root path="/home/site/deployments/tools/postgresql-42.2.12.jar" />
       </resources>
       <dependencies>
           <module name="javax.api"/>
           <module name="javax.transaction.api"/>
       </dependencies>
   </module>
   

3. Put your JBoss CLI commands into a file named jboss-cli-commands.cli. The JBoss commands must add the module and register it as a data source. The following example shows the JBoss CLI commands for PostgreSQL.

   #!/usr/bin/env bash
   module add --name=org.postgres --resources=/home/site/deployments/tools/postgresql-42.2.12.jar --module-xml=/home/site/deployments/tools/postgres-module.xml
   
   /subsystem=datasources/jdbc-driver=postgres:add(driver-name="postgres",driver-module-name="org.postgres",driver-class-name=org.postgresql.Driver,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)
   
   data-source add --name=postgresDS --driver-name=postgres --jndi-name=java:jboss/datasources/postgresDS --connection-url=${POSTGRES_CONNECTION_URL,env.POSTGRES_CONNECTION_URL:jdbc:postgresql://db:5432/postgres} --user-name=${POSTGRES_SERVER_ADMIN_FULL_NAME,env.POSTGRES_SERVER_ADMIN_FULL_NAME:postgres} --password=${POSTGRES_SERVER_ADMIN_PASSWORD,env.POSTGRES_SERVER_ADMIN_PASSWORD:example} --use-ccm=true --max-pool-size=5 --blocking-timeout-wait-millis=5000 --enabled=true --driver-class=org.postgresql.Driver --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter --jta=true --use-java-context=true --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
   

4. Create a startup script, startup_script.sh that calls the JBoss CLI commands. The following example shows how to call your jboss-cli-commands.cli. Later, you'll configure App Service to run this script when the container starts.

   $JBOSS_HOME/bin/jboss-cli.sh --connect --file=/home/site/deployments/tools/jboss-cli-commands.cli
   

5. Using an FTP client of your choice, upload your JDBC driver, jboss-cli-commands.cli, startup_script.sh, and the module definition to /site/deployments/tools/.

6. Configure your site to run startup_script.sh when the container starts. In the Azure portal, navigate to Configuration > General Settings > Startup Command. Set the startup command field to /home/site/deployments/tools/startup_script.sh. Save your changes.

To confirm that the datasource was added to the JBoss server, SSH into your webapp and run $JBOSS_HOME/bin/jboss-cli.sh --connect. Once you're connected to JBoss, run the /subsystem=datasources:read-resource to print a list of the data sources.

JBoss EAP

Clustering in JBoss EAP

App Service supports clustering for JBoss EAP versions 7.4.1 and greater. To enable clustering, your web app must be integrated with a virtual network. When the web app is integrated with a virtual network, it restarts, and the JBoss EAP installation automatically starts up with a clustered configuration. The JBoss EAP instances communicate over the subnet specified in the virtual network integration, using the ports shown in the WEBSITES_PRIVATE_PORTS environment variable at runtime. You can disable clustering by creating an app setting named WEBSITE_DISABLE_CLUSTERING with any value.

When clustering is enabled, the JBoss EAP instances use the FILE_PING JGroups discovery protocol to discover new instances and persist the cluster information like the cluster members, their identifiers, and their IP addresses. On App Service, these files are under /home/clusterinfo/. The first EAP instance to start obtains read/write permissions on the cluster membership file. Other instances read the file, find the primary node, and coordinate with that node to be included in the cluster and added to the file.

The Premium V3 and Isolated V2 App Service Plan types can optionally be distributed across Availability Zones to improve resiliency and reliability for your business-critical workloads. This architecture is also known as zone redundancy. The JBoss EAP clustering feature is compatible with the zone redundancy feature.

Autoscale Rules

When configuring autoscale rules for horizontal scaling, it's important to remove instances incrementally (one at a time) to ensure each removed instance can transfer its activity (such as handling a database transaction) to another member of the cluster. When configuring your autoscale rules in the Portal to scale down, use the following options:

• Operation: "Decrease count by"
• Cool down: "5 minutes" or greater
• Instance count: 1

You don't need to incrementally add instances (scaling out), you can add multiple instances to the cluster at a time.

JBoss EAP App Service Plans

JBoss EAP is only available on the Premium v3 and Isolated v2 App Service Plan types. Customers that created a JBoss EAP site on a different tier during the public preview should scale up to Premium or Isolated hardware tier to avoid unexpected behavior.

Tomcat Baseline Configuration On App Services

Java developers can customize the server settings, troubleshoot issues, and deploy applications to Tomcat with confidence if they know about the server.xml file and configuration details of Tomcat. Possible customizations include:

• Customizing Tomcat configuration: By understanding the server.xml file and Tomcat's configuration details, you can fine-tune the server settings to match the needs of their applications.
• Debugging: When an application is deployed on a Tomcat server, developers need to know the server configuration to debug any issues that might arise. This includes checking the server logs, examining the configuration files, and identifying any errors that might be occurring.
• Troubleshooting Tomcat issues: Inevitably, Java developers encounter issues with their Tomcat server, such as performance problems or configuration errors. By understanding the server.xml file and Tomcat's configuration details, developers can quickly diagnose and troubleshoot these issues, which can save time and effort.
• Deploying applications to Tomcat: To deploy a Java web application to Tomcat, developers need to know how to configure the server.xml file and other Tomcat settings. Understanding these details is essential for deploying applications successfully and ensuring that they run smoothly on the server.

When you create an app with built-in Tomcat to host your Java workload (a WAR file or a JAR file), there are certain settings that you get out of the box for Tomcat configuration. You can refer to the Official Apache Tomcat Documentation for detailed information, including the default configuration for Tomcat Web Server.

Additionally, there are certain transformations that are further applied on top of the server.xml for Tomcat distribution upon start. These are transformations to the Connector, Host, and Valve settings.

Note that the latest versions of Tomcat have server.xml (8.5.58 and 9.0.38 onward). Older versions of Tomcat don't use transforms and might have different behavior as a result.

Connector

<Connector port="${port.http}" address="127.0.0.1" maxHttpHeaderSize="16384" compression="on" URIEncoding="UTF-8" connectionTimeout="${site.connectionTimeout}" maxThreads="${catalina.maxThreads}" maxConnections="${catalina.maxConnections}" protocol="HTTP/1.1" redirectPort="8443"/>

• maxHttpHeaderSize is set to 16384
• URIEncoding is set to UTF-8
• conectionTimeout is set to WEBSITE_TOMCAT_CONNECTION_TIMEOUT, which defaults to 240000
• maxThreads is set to WEBSITE_CATALINA_MAXTHREADS, which defaults to 200
• maxConnections is set to WEBSITE_CATALINA_MAXCONNECTIONS, which defaults to 10000

Following are example CLI commands that you might use to alter the values of conectionTimeout, maxThreads, or maxConnections:

az webapp config appsettings set --resource-group myResourceGroup --name myApp --settings WEBSITE_TOMCAT_CONNECTION_TIMEOUT=120000

az webapp config appsettings set --resource-group myResourceGroup --name myApp --settings WEBSITE_CATALINA_MAXTHREADS=100

az webapp config appsettings set --resource-group myResourceGroup --name myApp --settings WEBSITE_CATALINA_MAXCONNECTIONS=5000

• Connector uses the address of the container instead of 127.0.0.1

Host

<Host appBase="${site.appbase}" xmlBase="${site.xmlbase}" unpackWARs="${site.unpackwars}" workDir="${site.tempdir}" errorReportValveClass="com.microsoft.azure.appservice.AppServiceErrorReportValve" name="localhost" autoDeploy="true">

• appBase is set to AZURE_SITE_APP_BASE, which defaults to local WebappsLocalPath
• xmlBase is set to AZURE_SITE_HOME, which defaults to /site/wwwroot
• unpackWARs is set to AZURE_UNPACK_WARS, which defaults to true
• workDir is set to JAVA_TMP_DIR, which defaults TMP
• errorReportValveClass uses our custom error report valve

Valve

<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}/http/RawLogs" maxDays="${site.logRetentionDays}" className="org.apache.catalina.valves.AccessLogValve" suffix=".txt"/>

• directory is set to AZURE_LOGGING_DIR, which defaults to home\logFiles
• maxDays is to WEBSITE_HTTPLOGGING_RETENTION_DAYS, which defaults to 0 [forever]

On Linux, it has all of the same customization, plus:

• Adds some error and reporting pages to the valve:

               <xsl:attribute name="appServiceErrorPage">
                   <xsl:value-of select="'${appService.valves.appServiceErrorPage}'"/>
               </xsl:attribute>

               <xsl:attribute name="showReport">
                   <xsl:value-of select="'${catalina.valves.showReport}'"/>
               </xsl:attribute>

               <xsl:attribute name="showServerInfo">
                   <xsl:value-of select="'${catalina.valves.showServerInfo}'"/>
               </xsl:attribute>