Maven Plugin for Azure App Service

Table of Content

Overview

Maven Central

The Maven Plugin for Azure App Service provides seamless integration into Maven projects, and makes it easier for developers to deploy your applications to following types of Azure App Service:

Prerequisites

Tool Required Version
JDK 1.7 or above
Maven 3.0 or above

Quick Start

  1. Make sure you have already authenticated in Azure. You can use the Azure CLI 2.0 for authentication. More authentication methods can be found here.

    • Install the Azure CLI 2.0 by following the instructions in the Install Azure CLI 2.0 article.
    • Run the following commands to log into your Azure subscription´╝Ü
        $ az login
        $ az account set --subscription <subscription Id>
    
  2. You could create a new Azure App Service and fill in the information in the pom.xml. This configuration can also be generated by azure-webapp:config.

    <build>
        <plugins>
            <plugin>
                <groupId>com.microsoft.azure</groupId>
                <artifactId>azure-webapp-maven-plugin</artifactId>
                <!-- check Maven Central for the latest version -->
                <version>1.5.3</version>
                <configuration>
                    <schemaVersion>v2</schemaVersion>
                    <resourceGroup>${RESOURCEGROUP_NAME}</resourceGroup>
                    <appName>${WEBAPP_NAME}</appName>
                    <runtime>
                        <os>linux</os>
                        <javaVersion>jre8</javaVersion>
                        <webContainer>tomcat 8.5</webContainer>
                    </runtime>
                    <deployment>
                        <resources>
                            <resource>
                                <directory>${project.basedir}/target</directory>
                                <includes>
                                    <include>*.war</include>
                                </includes>
                            </resource>
                        </resources>
                    </deployment>
                </configuration>
            </plugin>
        </plugins>
    </build>      
    
  3. Use the following commands to deploy your project to Azure App Service.

    $ mvn azure-webapp:deploy
    

Goals

azure-webapp:config

  • A plugin goal providing a great experience for managing the configuration of azure-webapp:deploy, it will add configurations for your App Service into your pom.xml or rewrite existing ones based on your input.
  • The plugin goal will divide the configuration into 3 parts.
    1. Application

      You can configure appName, resource group, region, pricing tier at this part.

    2. Runtime

      You can configure operating system and runtime stack at this part. It should be noted that you can not change the operating system after you deploy it.

    3. DeploymentSlot

      You can configure deployment slot at this part.

azure-webapp:deploy

  • Deploy artifacts or docker container image to an Azure Web App based on your configuration.
    If the specified Web App does not exist, it will be created.

  • Configuration: Common configurations of all Maven Plugins for Azure can be found here.

    Using v2 schema is recommended. Please click here if you want to find more details about v1 schema (deprecated).

    Property Required Description Version
    <schemaVersion> false Specify the version of the configuration schema. Supported values are: v1, v2. 1.5.2
    <region> true Specifies the region where your Web App will be hosted; the default value is westus. All valid regions at Supported Regions section. 0.1.0+
    <resourceGroup> true Azure Resource Group for your Web App. 0.1.0+
    <appName> true The name of your Web App. 0.1.0+
    <pricingTier> false The pricing tier for your Web App. The default value is P1V2. 0.1.0+
    <deploymentSlot> false The deployment slot to deploy your application. You could find detail samples for deployment slot at here. 1.3.0+
    <appServicePlanResourceGroup> false The resource group of the existing App Service Plan. If not specified, the value defined in <resourceGroup> will be used by default. 1.0.0+
    <appServicePlanName> false The name of the existing App Service Plan. 1.0.0+
    <appSettings> false Specifies the application settings for your Web App. You could find detail samples for appsettings at here. 0.1.0+
    <stopAppDuringDeployment> false To stop the target Web App or not during deployment. This will prevent deployment failure caused by IIS locking files. 0.1.4+
    <runtime> true The runtime environment configuration, you could see the detail here. 0.1.0+
    <deployment> true The deployment configuration, you could see the details here. 0.1.0+
  • Runtime settings

    Supported <os> values are Linux, Windows and Docker.

    The runtime settings of v2 configuration could be omitted if users specify an existing Web App in the configuration and just want to do the deployment directly.

    <configuration>        
        <runtime>
            <os>Linux</os>
            <javaVersion>jre8</javaVersion>
            <webContainer></webContainer>
        </runtime>        
    </configuration>
    
    <configuration>
        <runtime>
            <os>Docker</os>
            <!-- only image is required -->
            <image>[hub-user/]repo-name[:tag]</image>
            <serverId></serverId>
            <registryUrl></registryUrl>
        </runtime>
    </configuration>
    
  • Deployment settings

    Users don't need to care about the deployment type in v2 configuration. Just configure the resources to deploy to the Web App.

    It will use the zip deploy for fast and easy deploy. But if the artifact(s) are war package(s), war deploy will be used. Mix deploying war packages and other kinds of artifacts is not suggested and will cause errors.

    <configuration>
        ...
        <deployment>
         <resources>
          <resource>
            <directory>${project.basedir}/target</directory>
            <includes>
               <include>*.jar</include>
            </includes>            
          </resource>
         </resources>
        </deployment>
    </configuration>
    

Configuration Details

<javaVersion>

The supported values for Web App on Linux are jre8,java11.

The supported values for Web App on Windows:

Supported Value Description
1.7 Java 7, Newest minor version
1.7.0_51 Java 7, Update 51
1.7.0_71 Java 7, Update 71
1.8 Java 8, Newest minor version
1.8.0_25 Java 8, Update 25
1.8.0_60 Java 8, Update 60
1.8.0_73 Java 8, Update 73
1.8.0_111 Java 8, Update 111
1.8.0_92 Azul's Zulu OpenJDK 8, Update 92
1.8.0_102 Azul's Zulu OpenJDK 8, Update 102
11 Java 11
11.0.2_ZULU Azul's Zulu OpenJDK 11

Note: It is recommended to ignore the minor version number so that the latest supported JVM will be used in your Web App.

<webContainer>

The supported Value for web App on Linux

In Linux environment, if the <webcontainer> is not configured, JavaSE will be used as default. It means does not use any web container, just run your jar file.

Supported Value Description
tomcat 8.5 Newest Tomcat 8.5
tomcat 9.0 Tomcat 9.0
wildfly 14 WildFly 14 (For jre8 only)

The supported Value for web App on windows

In Windows environment, default value is tomcat 8.5

Supported Value Description
tomcat 7.0 Newest Tomcat 7.0
tomcat 7.0.50 Tomcat 7.0.50
tomcat 7.0.62 Tomcat 7.0.62
tomcat 8.0 Newest Tomcat 8.0
tomcat 8.0.23 Tomcat 8.0.23
tomcat 8.5 Newest Tomcat 8.5
tomcat 8.5.6 Tomcat 8.5.6
jetty 9.1 Newest Jetty 9.1
jetty 9.1.0.20131115 Jetty 9.1.0.v20131115
jetty 9.3 Newest Jetty 9.3
jetty 9.3.13.20161014 Jetty 9.3.13.v20161014

Note: It is recommended to ignore the minor version number so that the latest supported web container will be used in your Web App.

<resource>

Property Description
directory Specifies where the resources are stored.
targetPath Specifies the target path where the resources will be deployed to.
includes A list of patterns to include, e.g. **/*.war.
excludes A list of patterns to exclude, e.g. **/*.xml.

Note: The <targetPath> is relative to the /site/wwwroot/ folder except one case: it is relative to the /site/wwwroot/webapps when you deploy the war package.

<region>

Some valid regions are listed as below. All valid regions please refer to Azure Region Availability.

  • West US
  • West US 2
  • East Asia

<pricingTier>

Some valid pricing tiers are listed as below. All valid pricing tiers please refer to Azure App Service Plan Pricing.

  • F1
  • P1V2
  • P2V2

Samples

A few typical usages of Maven Plugin for Azure App Service Web Apps are listed at Web App Samples. You can choose one to quickly get started.

FeedBack and Questions

If you encounter any bugs with the maven plugins, please file an issue in the Issues section of our GitHub repo.

Data and Telemetry

This project collects usage data and sends it to Microsoft to help improve our products and services. Read Microsoft's privacy statement to learn more. If you would like to opt out of sending telemetry data to Microsoft, you can set allowTelemetry to false in the plugin configuration. Please read our documents to find more details.