Configure data sources for a Tomcat, or Java SE app in Azure App Service

Adding a shared, server-level data source requires you to edit Tomcat's server.xml. Because file changes outside of the /home directory are ephemeral, changes to Tomcat's configuration files need to be applied programatically, as follows:

• Upload a startup script and set the path to the script in Settings > Configuration. On the Stack settings tab, add the path in the Startup command box. You can upload the startup script by using FTP.

Your startup script makes an XSL transform to the server.xml file and outputs the resulting XML file to /usr/local/tomcat/conf/server.xml. The startup script should install libxslt or xlstproc, depending on the distribution of the version of Tomcat of your web app, as noted in the comment in the following example script. You can use FTP to upload your XSL file and startup script.

# Install the libxslt package on Alpine-based images:
apk add --update libxslt

# Install the xsltproc package on Debian or Ubuntu-based images:
apt install xsltproc

# Also copy the transform file to /home/tomcat/conf/
# 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 connector if there is 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 app.

• 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 resets CATALINA_BASE to /home/tomcat and uses the updated configuration.

You can't directly modify a Tomcat installation for server-wide configuration because the installation location is read-only. The easiest way to make server-level configuration changes to your Windows Tomcat installation is to complete the following steps on app start:

1. Copy Tomcat to a local directory (%LOCAL_EXPANDED%) and use that copy as CATALINA_BASE. (See the Tomcat documentation on this variable).
2. Add your shared data sources to %LOCAL_EXPANDED%\tomcat\conf\server.xml by using XSL transform.

Add a startup file

Create a file named startup.cmd in the %HOME%\site\wwwroot directory. This file runs automatically before the Tomcat server starts. The file should contain this:

C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -File  %HOME%\site\configure.ps1 > %HOME%\site\configure.log

Add the PowerShell configuration script

Next, add a configuration script called configure.ps1 to the %HOME%\site directory. The script contains this code:

# Locations of XML and XSL files
$source_xml = "$Env:AZURE_TOMCAT90_HOME\conf\server.xml"
$target_xml = "$Env:LOCAL_EXPANDED\tomcat\conf\server.xml"
$target_xsl = "$Env:HOME\site\server.xsl"
$marker_file = "$Env:HOME\site\config_done_marker"

# 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
        Write-Error 'Error'$ErrorMessage':'$FailedItem':' $_.Exception;
        return 0
    }
    return 1
}

# Start here

# Check for marker file indicating that configuration has already been done
if (Test-Path "$marker_file") {
    return 0
}

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

# Copy Tomcat to local
# When you use the environment variable $AZURE_TOMCAT90_HOME, the 'default' version of Tomcat is used
New-Item "$Env:LOCAL_EXPANDED\tomcat" -ItemType Directory
Copy-Item -Path "$Env:AZURE_TOMCAT90_HOME\*" "$Env:LOCAL_EXPANDED\tomcat" -Recurse

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

# Mark that the operation succeeded if it did
if ($success) {
    New-Item -Path "$marker_file" -ItemType File
}

This PowerShell completes the following steps:

1. Check whether a custom Tomcat copy exists. If one exists, the startup script can stop.
2. Copy Tomcat locally.
3. Add shared data sources to the custom Tomcat's configuration by using XSL transform.
4. Indicate that configuration completed successfully.

Add XSL transform file

A common use case for customizing the built-in Tomcat installation 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, you need to preserve the content of these files when you make changes to them. To preserve this content, use an XSL transformation (XSLT).

Add an XSL transform file called server.xsl to the %HOME%_\site directory. You can use the following XSL transform code to add a new connector node to server.xml. The identity transform at the beginning preserves the original contents of the configuration file.

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

    <!-- Identity transform: this transform 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 connector if there is 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>

Set the CATALINA_BASE app setting

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"

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

1. Go to Settings > Environmental variables > App settings.
2. Select Add.
3. Use these values to create the setting:
   1. Name: CATALINA_BASE
   2. Value: "%LOCAL_EXPANDED%\tomcat"

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