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

This article shows you the most common deployment and runtime configuration for Java apps in App Service. If you've never used Azure App Service, you should read through the Java quickstart first. General questions about using App Service that aren't specific to Java development are answered in the App Service FAQ.

Azure App Service runs Java web applications on a fully managed service in three variants:

• Java SE - Can run an app deployed as a JAR package that contains an embedded server (such as Spring Boot, Dropwizard, Quarkus, or one with an embedded Tomcat or Jetty server).
• Tomcat - The built-in Tomcat server can run an app deployed as a WAR package.

Show Java version

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

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

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

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

For more information on version support, see App Service language runtime support policy.

Deploying your app

Build Tools

Maven

With the Maven Plugin for Azure Web Apps, you can prepare your Maven Java project for Azure Web App easily with one command in your project root:

mvn com.microsoft.azure:azure-webapp-maven-plugin:2.13.0:config

This command adds an azure-webapp-maven-plugin plugin and related configuration by prompting you to select an existing Azure Web App or create a new one. During configuration, it attempts to detect whether your application should be deployed to Java SE, Tomcat. Then you can deploy your Java app to Azure using the following command:

mvn package azure-webapp:deploy

Here's a sample configuration in pom.xml:

<plugin> 
  <groupId>com.microsoft.azure</groupId>  
  <artifactId>azure-webapp-maven-plugin</artifactId>  
  <version>2.11.0</version>  
  <configuration>
    <subscriptionId>111111-11111-11111-1111111</subscriptionId>
    <resourceGroup>spring-boot-xxxxxxxxxx-rg</resourceGroup>
    <appName>spring-boot-xxxxxxxxxx</appName>
    <pricingTier>B2</pricingTier>
    <region>westus</region>
    <runtime>
      <os>Linux</os>      
      <webContainer>Java SE</webContainer>
      <javaVersion>Java 17</javaVersion>
    </runtime>
    <deployment>
      <resources>
        <resource>
          <type>jar</type>
          <directory>${project.basedir}/target</directory>
          <includes>
            <include>*.jar</include>
          </includes>
        </resource>
      </resources>
    </deployment>
  </configuration>
</plugin> 

Gradle

1. Set up the Gradle Plugin for Azure Web Apps by adding the plugin to your build.gradle:

   plugins {
     id "com.microsoft.azure.azurewebapp" version "1.10.0"
   }
   

2. Configure your web app details. The corresponding Azure resources are created if they don't exist. Here's a sample configuration, for details, refer to this document.

   azurewebapp {
       subscription = '<your subscription id>'
       resourceGroup = '<your resource group>'
       appName = '<your app name>'
       pricingTier = '<price tier like 'P1v2'>'
       region = '<region like 'westus'>'
       runtime {
         os = 'Linux'
         webContainer = 'Tomcat 10.0' // or 'Java SE' if you want to run an executable jar
         javaVersion = 'Java 17'
       }
       appSettings {
           <key> = <value>
       }
       auth {
           type = 'azure_cli' // support azure_cli, oauth2, device_code and service_principal
       }
   }
   

3. Deploy with one command.

   gradle azureWebAppDeploy
   

IDEs

Azure provides seamless Java App Service development experience in popular Java IDEs, including:

• VS Code: Java Web Apps with Visual Studio Code
• IntelliJ IDEA:Create a Hello World web app for Azure App Service using IntelliJ
• Eclipse:Create a Hello World web app for Azure App Service using Eclipse

Kudu API

Don't deploy your .war or .jar using FTP. The FTP tool is designed to upload startup scripts, dependencies, or other runtime files. It's not the optimal choice for deploying web apps.

Rewrite or redirect URL

To rewrite or redirect URL, use one of the available URL rewriters, such as UrlRewriteFilter.

Logging and debugging apps

Performance reports, traffic visualizations, and health checkups are available for each app through the Azure portal.

Stream diagnostic logs

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

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

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

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

SSH console access in Linux

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.chinacloudsites.cn/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.

Linux 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.

Java Profiler

All Java runtimes on Azure App Service come with the JDK Flight Recorder for profiling Java workloads. You can use it to record JVM, system, and application events and troubleshoot problems in your applications.

To learn more about the Java Profiler, visit the Azure Application Insights documentation.

Flight Recorder

All Java runtimes on App Service come with the Java Flight Recorder. You can use it to record JVM, system, and application events and troubleshoot problems in your Java applications.

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

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

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

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

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

Analyze .jfr files

Use FTPS to download your JFR file to your local machine. To analyze the JFR file, download and install Java Mission Control. For instructions on Java Mission Control, see the JMC documentation and the installation instructions.

App logging

If your application uses Logback or Log4j for tracing, you can forward these traces for review into Azure Application Insights using the logging framework configuration instructions in Explore Java trace logs in Application Insights.

Customization and tuning

Azure App Service supports out of the box tuning and customization through the Azure portal and CLI. Review the following articles for non-Java-specific web app configuration:

• Configure app settings
• Set up a custom domain
• Configure TLS/SSL bindings
• Configure the Kudu site

Copy App Content Locally

Set the app setting JAVA_COPY_ALL to true to copy your app contents to the local worker from the shared file system. This setting helps address file-locking issues.

Set Java runtime options

To set allocated memory or other JVM runtime options, create an app setting named JAVA_OPTS with the options. App Service passes this setting as an environment variable to the Java runtime when it starts.

To configure the app setting from the Maven plugin, add setting/value tags in the Azure plugin section. The following example sets a specific minimum and maximum Java heap size:

<appSettings>
    <property>
        <name>JAVA_OPTS</name>
        <value>-Xms1024m -Xmx1024m</value>
    </property>
</appSettings>

Developers running a single application with one deployment slot in their App Service plan can use the following options:

• B1 and S1 instances: -Xms1024m -Xmx1024m
• B2 and S2 instances: -Xms3072m -Xmx3072m
• B3 and S3 instances: -Xms6144m -Xmx6144m
• P1v2 instances: -Xms3072m -Xmx3072m
• P2v2 instances: -Xms6144m -Xmx6144m
• P3v2 instances: -Xms12800m -Xmx12800m
• P1v3 instances: -Xms6656m -Xmx6656m
• P2v3 instances: -Xms14848m -Xmx14848m
• I1 instances: -Xms3072m -Xmx3072m
• I2 instances: -Xms6144m -Xmx6144m
• I3 instances: -Xms12800m -Xmx12800m
• I1v2 instances: -Xms6656m -Xmx6656m
• I2v2 instances: -Xms14848m -Xmx14848m
• I3v2 instances: -Xms30720m -Xmx30720m

When tuning application heap settings, review your App Service plan details and take into account multiple applications and deployment slot needs to find the optimal allocation of memory.

Turn on web sockets

Turn on support for web sockets in the Azure portal in the Application settings for the application. You need to restart the application for the setting to take effect.

Turn on web socket support using the Azure CLI with the following command:

az webapp config set --name <app-name> --resource-group <resource-group-name> --web-sockets-enabled true

Then restart your application:

az webapp stop --name <app-name> --resource-group <resource-group-name>
az webapp start --name <app-name> --resource-group <resource-group-name>

Set default character encoding

In the Azure portal, under Application Settings for the web app, create a new app setting named JAVA_OPTS with value -Dfile.encoding=UTF-8.

Alternatively, you can configure the app setting using the App Service Maven plugin. Add the setting name and value tags in the plugin configuration:

<appSettings>
    <property>
        <name>JAVA_OPTS</name>
        <value>-Dfile.encoding=UTF-8</value>
    </property>
</appSettings>

robots933456 in logs

You may see the following message in the container logs:

2019-04-08T14:07:56.641002476Z "-" - - [08/Apr/2019:14:07:56 +0000] "GET /robots933456.txt HTTP/1.1" 404 415 "-" "-"

You can safely ignore this message. /robots933456.txt is a dummy URL path that App Service uses to check if the container is capable of serving requests. A 404 response simply indicates that the path doesn't exist, but it lets App Service know that the container is healthy and ready to respond to requests.

Choosing a Java runtime version

App Service allows users to choose the major version of the JVM, such as Java 8 or Java 11, and the patch version, such as 1.8.0_232 or 11.0.5. You can also choose to have the patch version automatically updated as new minor versions become available. In most cases, production apps should use pinned patch JVM versions. This prevents unanticipated outages during a patch version autoupdate. All Java web apps use 64-bit JVMs, and it's not configurable.

If you choose to pin the minor version, you need to periodically update the JVM minor version on the app. To ensure that your application runs on the newer minor version, create a staging slot and increment the minor version on the staging slot. Once you confirm the application runs correctly on the new minor version, you can swap the staging and production slots.

<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"/>

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

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

<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"/>

Next steps

Visit the Azure for Java Developers center to find Azure quickstarts, tutorials, and Java reference documentation.

• App Service Linux FAQ
• Environment variables and app settings reference