Deploy and configure a Tomcat, JBoss, or Java SE app in Azure App Service

To deploy .jar files to Java SE, use the /api/publish endpoint of the Kudu site. For more information on this API, see this documentation.

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

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.

Tomcat also provides a rewrite valve.

JBoss also provides a rewrite valve.

In the Azure portal, under Application Settings for the web app, create a new app setting named JAVA_OPTS that includes other settings, such as -Xms512m -Xmx1204m.

In the Azure portal, under Application Settings for the web app, create a new app setting named CATALINA_OPTS that includes other settings, such as -Xms512m -Xmx1204m.

Pre-Compile JSP files

To improve performance of Tomcat applications, you can compile your JSP files before deploying to App Service. You can use the Maven plugin provided by Apache Sling, or using this Ant build file.

If you're using Tomcat, you can choose to pin the patch version of Tomcat. On Windows, you can pin the patch versions of the JVM and Tomcat independently. On Linux, you can pin the patch version of Tomcat; the patch version of the JVM is also pinned but isn't separately configurable.

Run JBoss CLI

In your JBoss app's SSH session, you can run the JBoss CLI with the following command:

$JBOSS_HOME/bin/jboss-cli.sh --connect

Depending on where JBoss is in the server lifecycle, you might not be able to connect. Wait a few minutes and try again. This approach is useful for quick checks of your current server state (for example, to see if a data source is properly configured).

Also, changes you make to the server with JBoss CLI in the SSH session doesn't persist after the app restarts. Each time the app starts, the JBoss EAP server begins with a clean installation. During the startup lifecycle, App Service makes the necessary server configurations and deploys the app. To make any persistent changes in the JBoss server, use a custom startup script or a startup command. For an end-to-end example, see Configure data sources for a Tomcat, JBoss, or Java SE app in Azure App Service.

Alternatively, you can manually configure App Service to run any file on startup. For example:

az webapp config set --resource-group <group-name> --name <app-name> --startup-file /home/site/scripts/foo.sh

For more information about the CLI commands you can run, see:

• Red Hat JBoss EAP documentation
• WildFly CLI Recipes

Clustering

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. When you run multiple instances with autoscaling, the JBoss EAP instances communicate with each other over the subnet specified in the virtual network integration. 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.

App Service plans

JBoss EAP is available in the following pricing tiers: F1, P0v3, P1mv3, P2mv3, P3mv3, P4mv3, and P5mv3.

JBoss server lifecycle

A JBoss EAP app in App Service goes through five distinct phases before actually launching the server.

• 1. Environment setup phase
• 2. Server launch phase
• 3. Server configuration phase
• 4. App deployment phase
• 5. Server reload phase

See respective sections below for details as well as opportunities to customize it (such as through app settings).

1. Environment setup phase

• The SSH service is started to enable secure SSH sessions with the container.
• The Keystore of the Java runtime is updated with any public and private certificates defined in Azure portal.
  • Public certificates are provided by the platform in the /var/ssl/certs directory, and they're loaded to $JRE_HOME/lib/security/cacerts.
  • Private certificates are provided by the platform in the /var/ssl/private directory, and they're loaded to $JRE_HOME/lib/security/client.jks.
• If any certificates are loaded in the Java keystore in this step, the properties javax.net.ssl.keyStore, javax.net.ssl.keyStorePassword and javax.net.ssl.keyStoreType are added to the JAVA_TOOL_OPTIONS environment variable.
• Some initial JVM configuration is determined such as logging directories and Java memory heap parameters:
  • If you provide the –Xms or –Xmx flags for memory in the app setting JAVA_OPTS, these values override the ones provided by the platform.
  • If you configure the app setting WEBSITES_CONTAINER_STOP_TIME_LIMIT, the value is passed to the runtime property org.wildfly.sigterm.suspend.timeout, which controls the maximum shutdown wait time (in seconds) when JBoss is being stopped.
• If the app is integrated with a virtual network, the App Service runtime passes a list of ports to be used for inter-server communication in the environment variable WEBSITE_PRIVATE_PORTS and launch JBoss using the clustering configuration. Otherwise, the standalone configuration is used.
  • For the clustering configuration, the server configuration file standalone-azure-full-ha.xml is used.
  • For the standalone configuration, the server configuration file standalone-full.xml is used.

2. Server launch phase

• If JBoss is launched in the clustering configuration:
  • Each JBoss instance receives an internal identifier between 0 and the number of instances that the app is scaled out to.
  • If some files are found in the transaction store path for this server instance (by using its internal identifier), it means this server instance is taking the place of an identical service instance that crashed previously and left uncommitted transactions behind. The server is configured to resume the work on these transactions.
• Regardless if JBoss starting in the clustering or standalone configuration, if the server version is 7.4 or above and the runtime uses Java 17, then the configuration is updated to enable the Elytron subsystem for security.
• If you configure the app setting WEBSITE_JBOSS_OPTS, the value is passed to the JBoss launcher script. This setting can be used to provide paths to property files and more flags that influence the startup of JBoss.

3. Server configuration phase

• At the start of this phase, App Service first waits for both the JBoss server and the admin interface to be ready to receive requests before continuing. This can take a few more seconds if Application Insights is enabled.
• When both JBoss Server and the admin interface are ready, App Service does the following:
  • Adds the JBoss module azure.appservice, which provides utility classes for logging and integration with App Service.
  • Updates the console logger to use a colorless mode so that log files aren't full of color escaping sequences.
  • Sets up the integration with Azure Monitor logs.
  • Updates the binding IP addresses of the WSDL and management interfaces.
  • Adds the JBoss module azure.appservice.easyauth for integration with App Service authentication and Microsoft Entra ID.
  • Updates the logging configuration of access logs and the name and rotation of the main server log file.
• Unless the app setting WEBSITE_SKIP_AUTOCONFIGURE_DATABASE is defined, App Service autodetects JDBC URLs in the App Service app settings. If valid JDBC URLs exist for PostgreSQL, MySQL, MariaDB, Oracle, SQL Server, or Azure SQL Database, it adds the corresponding driver(s) to the server and adds a data source for each of the JDBC URL and sets the JNDI name for each data source to java:jboss/env/jdbc/<app-setting-name>_DS, where <app-setting-name> is the name of the app setting.
• If the clustering configuration is enabled, the console logger to be configured is checked.
• If there are JAR files deployed to the /home/site/libs directory, a new global module is created with all of these JAR files.
• At the end of the phase, App Service runs the custom startup script, if one exists. The search logic for the custom startup script as follows:
  • If you configured a startup command (in the Azure portal, with Azure CLI, etc.), run it; otherwise,
  • If the path /home/site/scripts/startup.sh exists, use it; otherwise,
  • If the path /home/startup.sh exists, use it.

The custom startup command or script runs as the root user (no need for sudo), so they can install Linux packages or launch the JBoss CLI to perform more JBoss install/customization commands (creating datasources, installing resource adapters), etc. For information on Ubuntu package management commands, see the Ubuntu Server documentation. For JBoss CLI commands, see the JBoss Management CLI Guide.

4. App deployment phase

The startup script deploys apps to JBoss by looking in the following locations, in order of precedence:

• If you configured the app setting WEBSITE_JAVA_WAR_FILE_NAME, deploy the file designated by it.
• If /home/site/wwwroot/app.war exists, deploy it.
• If any other EAR and WAR files exist in /home/site/wwwroot, deploy them.
• If /home/site/wwwroot/webapps exists, deploy the files and directories in it. WAR files are deployed as applications themselves, and directories are deployed as "exploded" (uncompressed) web apps.
• If any standalone JSP pages exist in /home/site/wwwroot, copy them to the web server root and deploy them as one web app.
• If no deployable files are found yet, deploy the default welcome page (parking page) in the root context.

5. Server reload phase

• Once the deployment steps are complete, the JBoss server is reloaded to apply any changes that require a server reload.
• After the server reloads, the application(s) deployed to JBoss EAP server should be ready to respond to requests.
• The server runs until the App Service app is stopped or restarted. You can manually stop or restart the App Service app, or you trigger a restart when you deploy files or make configuration changes to the App Service app.
• If the JBoss server exits abnormally in the clustering configuration, a final function called emit_alert_tx_store_not_empty is executed. The function checks if the JBoss process left a nonempty transaction store file in disk; if so, an error is logged in the console: Error: finishing server with non-empty store for node XXXX. When a new server instance is started, it looks for these nonempty transaction store files to resume the work (see 2. Server launch phase).

Tomcat baseline configuration

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.

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
• connectionTimeout 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 connectionTimeout, 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 7. This aligns with the Application Logging platform default

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>