Quickstart: Create a Java app on Azure App Service

Azure App Service provides a highly scalable, self-patching web app hosting service. This quickstart shows how to use the Azure CLI with the Azure Web App Plugin for Maven to deploy a .jar, .war or .ear file. Use the tabs to switch between Java SE, Tomcat, and JBoss EAP instructions.

If Maven isn't your preferred development tool, check out our similar tutorials for Java developers:

If you don't have an Azure subscription, create an Azure free account before you begin.

1 - Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article, without having to install anything on your local environment.

To start Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code or command block. Selecting Try It doesn't automatically copy the code or command to Cloud Shell. Screenshot that shows an example of Try It for Azure Cloud Shell.
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Screenshot that shows how to launch Cloud Shell in a new window.
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal. Screenshot that shows the Cloud Shell button in the Azure portal

To use Azure Cloud Shell:

  1. Start Cloud Shell.

  2. Select the Copy button on a code block (or command block) to copy the code or command.

  3. Paste the code or command into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux, or by selecting Cmd+Shift+V on macOS.

  4. Select Enter to run the code or command.

Install Java 17, if desired

If you intend to run the Java SE sections of this quickstart, the sample app requires Java 17. The steps in this section show you how to check if your Cloud Shell instance supports Java 17, and how to install it does not.

  1. In the Azure Cloud Shell, enter java -version. If the output includes a version 17 or later, skip the rest of the steps in this section.

  2. Enter these commands to download and extract the Microsoft build of OpenJDK.

    wget https://aka.ms/download-jdk/microsoft-jdk-17-linux-x64.tar.gz
    tar -zxf microsoft-jdk-17*.tar.gz
    
  3. Enter these commands to override the built-in Open JDK installed in Azure Cloud Shell.

    Tip

    You must do this every time you open a new cloud shell, because the environment variables do not persist across cloud shell invocations. However, the files do persist.

    cd jdk-17*
    export JAVA_HOME=`pwd`
    cd ..
    export PATH=${JAVA_HOME}/bin:$PATH
    java -version
    

You should see output stating the version of Java is 17 or greater. If not, troubleshoot and resolve the problem before continuing.

2 - Create a Java app

Clone the sample project and check out the source code that runs with this version of the article.

Tip

Though App Service supports older versions of Java, the booty-duke-app-service sample project uses Java records and requires Java 17. For more information about Java records, see JEP 395.

git clone https://github.com/Azure-Samples/app-service-java-quickstart

Change directory to the completed project and build from the top level. Then cd to the subdirectory for booty duke.

cd app-service-java-quickstart
git checkout 20230308
mvn clean install
cd booty-duke-app-service

If you see a message about being in detached HEAD state, this message is safe to ignore. Because you will not be making any commits, detached HEAD state is appropriate.

3 - Configure the Maven plugin

Tip

The Maven plugin supports Java 17 and Tomcat 10.0. For more information about latest support, see Java 17 and Tomcat 10.0 are available on Azure App Service.

The deployment process to Azure App Service uses your Azure credentials from the Azure CLI automatically. If the Azure CLI isn't installed locally, then the Maven plugin authenticates with Oauth or device login. For more information, see authentication with Maven plugins.

Run the Maven command shown next to configure the deployment. This command helps you to set up the App Service operating system, Java version, and Tomcat version.

mvn com.microsoft.azure:azure-webapp-maven-plugin:2.11.0:config
  1. If prompted for Create new run configuration, select Y.

  2. When prompted with Subscription option, select the proper Subscription by entering the number printed at the start of the line.

  3. When prompted with Web App option, select the default option, <create>, by pressing enter.

  4. When prompted with OS option, select Linux by pressing enter.

  5. When prompted with javaVersion option, select Java 17.

  6. When prompted with Pricing Tier option, select P1v2.

  7. Finally, press enter on the last prompt to confirm your selections.

    Please confirm webapp properties
    AppName : booty-duke-1678285507374
    ResourceGroup : booty-duke-1678285507374-rg
    Region : centralus
    PricingTier : P1v2
    OS : Linux
    Java Version: Java 17
    Web server stack: Java SE
    Deploy to slot : false
    Confirm (Y/N) [Y]: Y
    [INFO] Saving configuration to pom.
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time:  01:03 min
    [INFO] Finished at: 2023-03-08T15:25:47+01:00
    [INFO] ------------------------------------------------------------------------
    

You can modify the configurations for App Service directly in your pom.xml. Some common configurations are listed below:

Property Required Description Version
<schemaVersion> false Specify the version of the configuration schema. Supported values are: v1, v2. 1.5.2
<subscriptionId> false Specify the subscription ID. 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+
<region> false Specifies the region to host your Web App; the default value is centralus. All valid regions at Supported Regions section. 0.1.0+
<pricingTier> false The pricing tier for your Web App. The default value is P1v2 for production workload, while B2 is the recommended minimum for Java dev/test. For more information, see App Service Pricing 0.1.0+
<runtime> false The runtime environment configuration. For more information, see Configuration Details. 0.1.0+
<deployment> false The deployment configuration. For more information, see Configuration Details. 0.1.0+

For the complete list of configurations, see the plugin reference documentation. All the Azure Maven Plugins share a common set of configurations. For these configurations see Common Configurations. For configurations specific to App Service, see Azure Web App: Configuration Details.

Be careful about the values of <appName> and <resourceGroup> (helloworld-1590394316693 and helloworld-1590394316693-rg accordingly in the demo), they are used later.

4 - Deploy the app

With all the configuration ready in your pom file, you can deploy your Java app to Azure with one single command.

mvn package azure-webapp:deploy

Once deployment is completed, your application is ready at http://<appName>.azurewebsites.net/ (http://helloworld-1590394316693.azurewebsites.net in the demo). Open the url with your local web browser, you should see

Congratulations! You've deployed your first Java app to App Service.

5 - Clean up resources

In the preceding steps, you created Azure resources in a resource group. If you don't need the resources in the future, delete the resource group from portal, or by running the following command in the Cloud Shell:

az group delete --name <your resource group name; for example: helloworld-1558400876966-rg> --yes

This command may take a minute to run.

Azure App Service provides a highly scalable, self-patching web app hosting service. This quickstart shows how to use the Azure CLI with the Azure Web App Plugin for Maven to deploy a .jar file or .war file. Use the tabs to switch between Java SE and Tomcat instructions.

Screenshot of Spring app greetings in Azure App Service.

If Maven isn't your preferred development tool, check out our similar tutorials for Java developers:

If you don't have an Azure subscription, create an Azure free account before you begin.

1 - Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article, without having to install anything on your local environment.

To start Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code or command block. Selecting Try It doesn't automatically copy the code or command to Cloud Shell. Screenshot that shows an example of Try It for Azure Cloud Shell.
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Screenshot that shows how to launch Cloud Shell in a new window.
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal. Screenshot that shows the Cloud Shell button in the Azure portal

To use Azure Cloud Shell:

  1. Start Cloud Shell.

  2. Select the Copy button on a code block (or command block) to copy the code or command.

  3. Paste the code or command into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux, or by selecting Cmd+Shift+V on macOS.

  4. Select Enter to run the code or command.

2 - Create a Java app

Clone the Spring Boot Getting Started sample project.

git clone https://github.com/spring-guides/gs-spring-boot

Change directory to the completed project.

cd gs-spring-boot/complete

3 - Configure the Maven plugin

Tip

The Maven plugin supports Java 17 and Tomcat 10.0. For more information about latest support, see Java 17 and Tomcat 10.0 are available on Azure App Service.

The deployment process to Azure App Service will use your Azure credentials from the Azure CLI automatically. If the Azure CLI is not installed locally, then the Maven plugin will authenticate with Oauth or device login. For more information, see authentication with Maven plugins.

Run the Maven command below to configure the deployment. This command will help you to set up the App Service operating system, Java version, and Tomcat version.

mvn com.microsoft.azure:azure-webapp-maven-plugin:2.11.0:config
  1. If prompted with Subscription option, select the proper Subscription by entering the number printed at the line start.

  2. When prompted with Web App option, select the default option, <create>, by pressing enter.

  3. When prompted with OS option, select Windows.

  4. When prompted with javaVersion option, select Java 11.

  5. When prompted with Pricing Tier option, select P1v2.

  6. Finally, press enter on the last prompt to confirm your selections.

    Your summary output will look similar to the snippet shown below.

    Please confirm webapp properties
    Subscription Id : ********-****-****-****-************
    AppName : spring-boot-1599007390755
    ResourceGroup : spring-boot-1599007390755-rg
    Region : centralus
    PricingTier : P1v2
    OS : Windows
    Java : Java 11
    Web server stack : Java SE
    Deploy to slot : false
    Confirm (Y/N)? : Y
    [INFO] Saving configuration to pom.
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 41.118 s
    [INFO] Finished at: 2020-09-01T17:43:45-07:00
    [INFO] ------------------------------------------------------------------------
    

You can modify the configurations for App Service directly in your pom.xml. Some common configurations are listed below:

Property Required Description Version
<schemaVersion> false Specify the version of the configuration schema. Supported values are: v1, v2. 1.5.2
<subscriptionId> false Specify the subscription ID. 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+
<region> false Specifies the region where your Web App will be hosted; the default value is centralus. All valid regions at Supported Regions section. 0.1.0+
<pricingTier> false The pricing tier for your Web App. The default value is P1v2 for production workload, while B2 is the recommended minimum for Java dev/test. For more information, see App Service Pricing 0.1.0+
<runtime> false The runtime environment configuration. For more information, see Configuration Details. 0.1.0+
<deployment> false The deployment configuration. For more information, see Configuration Details. 0.1.0+

Be careful about the values of <appName> and <resourceGroup> (helloworld-1590394316693 and helloworld-1590394316693-rg accordingly in the demo), they'll be used later.

4 - Deploy the app

With all the configuration ready in your pom file, you can deploy your Java app to Azure with one single command.

mvn package azure-webapp:deploy

Once deployment is completed, your application will be ready at http://<appName>.azurewebsites.net/ (http://helloworld-1590394316693.azurewebsites.net in the demo). Open the url with your local web browser, you should see

Screenshot of Spring app greetings in Azure App Service.

Congratulations! You've deployed your first Java app to App Service.

5 - Clean up resources

In the preceding steps, you created Azure resources in a resource group. If you don't need the resources in the future, delete the resource group from portal, or by running the following command in the Cloud Shell:

az group delete --name <your resource group name; for example: helloworld-1558400876966-rg> --yes

This command may take a minute to run.

Azure App Service provides a highly scalable, self-patching web app hosting service. This quickstart tutorial shows how to deploy a Java SE app to Azure App Service on Linux using the Azure portal. To follow a quickstart that deploys to Tomcat or JBoss EAP, select one of the Maven options above.

This quickstart configures an App Service app in the Free tier and incurs no cost for your Azure subscription.

This quickstart shows you how to make these changes within your browser, without having to install the development environment tools on your machine.

You can follow the steps here using a Mac, Windows, or Linux machine. Once the prerequisites are installed, it takes about five minutes to complete the steps.

To complete this quickstart you need:

  1. An Azure account with an active subscription. Create an account for free.
  2. A GitHub account to fork a repository.

1 - Fork the sample repository

  1. In your browser, navigate to the repository containing the sample code.

  2. In the upper right corner, select Fork.

    Screenshot of the Azure-Samples/java-docs-spring-hello-world repo in GitHub, with the Fork option highlighted.

  3. On the Create a new fork screen, confirm the Owner and Repository name fields. Select Create fork.

    Screenshot of the Create a new fork page in GitHub for creating a new fork of Azure-Samples/java-docs-spring-hello-world.

    Note

    This should take you to the new fork. Your fork URL will look something like this: https://github.com/YOUR_GITHUB_ACCOUNT_NAME/java-docs-spring-hello-world

2 - Create Azure resources and configure deployment

  1. Log in to the Azure portal.

  2. Type app services in the search. Under Services, select App Services.

    Screenshot of the Azure portal with 'app services' typed in the search text box. In the results, the App Services option under Services is highlighted.

  3. In the App Services page, select Create.

    Screenshot of the App Services page in the Azure portal. The Create button in the action bar is highlighted.

  4. Fill out the Create Web App page as follows.

  • Resource Group: Create a resource group named myResourceGroup.
  • Name: Type a globally unique name for your web app.
  • Publish: Select Code.
  • Runtime stack: Select Java 11.
  • Java web-server stack: Select Java SE (Embedded Web Server).
  • Operating system: Select Linux.
  • Region: Select an Azure region close to you.
  • App Service Plan: Create an app service plan named myAppServicePlan.
  1. To change the App Service Plan tier, next to Sku and size, select Change size.

  2. In the Spec Picker, on the Production tab, select P1V3. Select the Apply button at the bottom of the page.

    Screenshot of the Spec Picker for the App Service Plan pricing tiers in the Azure portal. Production, P1V3, and Apply are highlighted.

  3. Select the Review + create button at the bottom of the page.

  4. After validation runs, select the Create button at the bottom of the page. This will create an Azure resource group, app service plan, and app service.

  5. After the Azure resources are created, select Go to resource.

  6. From the left navigation, select Deployment Center.

    Screenshot of the App Service in the Azure Portal. The Deployment Center option in the Deployment section of the left navigation is highlighted.

  7. Under Settings, select a Source. For this quickstart, select GitHub.

  8. In the section under GitHub, select the following settings:

  • Organization: Select your organization.
  • Repository: Select java-docs-spring-hello-world.
  • Branch: Select main.
  1. Select Save.

    Screenshot of the Deployment Center for the App Service, focusing on the GitHub integration settings. The Save button in the action bar is highlighted.

    Tip

    This quickstart uses GitHub. Additional continuous deployment sources include Bitbucket, Local Git, Azure Repos, and External Git. FTPS is also a supported deployment method.

  2. Once the GitHub integration is saved, select Overview > URL.

    Screenshot of the App Service resource's overview with the URL highlighted.

The Java SE sample code is running in an Azure App Service Linux web app.

Screenshot of the sample app running in Azure, showing 'Hello World!'.

Congratulations! You've deployed your first Java app to App Service using the Azure portal.

3 - Update the fork in GitHub and deploy the changes

  1. Browse to your GitHub fork of java-docs-spring-hello-world.

  2. On your repo page, press . to start Visual Studio Code within your browser.

    Note

    The URL will change from GitHub.com to GitHub.dev. This feature only works with repos that have files. This does not work on empty repos.

    Screenshot of forked GitHub repo with an annotation to Press the period key.

  3. Navigate to src/main/java/com/example/demo/DemoApplication.java.

    Screenshot of Visual Studio Code in the browser, highlighting src/main/java/com/example/demo/DemoApplication.java in the Explorer pane.

  4. Edit the sayHello method so that it shows "Hello Azure!" instead of "Hello World!"

    @RequestMapping("/")
    String sayHello() {
        return "Hello Azure!";
    }
    
  5. From the Source Control pane, select the Stage Changes button to stage the change.

    Screenshot of Visual Studio Code in the browser, highlighting the Source Control navigation in the sidebar, then highlighting the Stage Changes button in the Source Control panel.

  6. Enter a commit message such as Hello Azure. Then, select Commit and Push.

    Screenshot of Visual Studio Code in the browser, Source Control panel with a commit message of 'Hello Azure' and the Commit and Push button highlighted.

  7. Once deployment has completed, return to the browser window that opened during the Browse to the app step, and refresh the page.

    Screenshot of the updated sample app running in Azure, showing 'Hello Azure!'.

4 - Manage your new Azure app

  1. Go to the Azure portal to manage the web app you created. Search for and select App Services.

    Screenshot of the Azure portal with 'app services' typed in the search text box. In the results, the App Services option under Services is highlighted.

  2. Select the name of your Azure app.

    Screenshot of the App Services list in Azure. The name of the demo app service is highlighted.

Your web app's Overview page will be displayed. Here, you can perform basic management tasks like Browse, Stop, Restart, and Delete.

Screenshot of the App Service overview page in Azure portal. In the action bar, the Browse, Stop, Swap (disabled), Restart, and Delete button group is highlighted.

The web app menu provides different options for configuring your app.

5 - Clean up resources

When you're finished with the sample app, you can remove all of the resources for the app from Azure. It will not incur extra charges and keep your Azure subscription uncluttered. Removing the resource group also removes all resources in the resource group and is the fastest way to remove all Azure resources for your app.

  1. From your App Service Overview page, select the resource group you created earlier.

  2. From the resource group page, select Delete resource group. Confirm the name of the resource group to finish deleting the resources.

Azure App Service provides a highly scalable, self-patching web app hosting service. This quickstart tutorial shows how to deploy a Java SE app to Azure App Service on Windows using the Azure portal. To follow a quickstart that deploys to Tomcat or JBoss EAP, select one of the Maven options above.

This quickstart configures an App Service app in the Free tier and incurs no cost for your Azure subscription.

This quickstart shows you how to make these changes within your browser, without having to install the development environment tools on your machine.

Screenshot of the sample Java SE app running in Azure, showing 'Hello World!'.

You can follow the steps here using a Mac, Windows, or Linux machine. Once the prerequisites are installed, it takes about five minutes to complete the steps.

To complete this quickstart you need:

  1. An Azure account with an active subscription. Create an account for free.
  2. A GitHub account to fork a repository.

1 - Fork the sample repository

  1. In your browser, navigate to the repository containing the sample code.

  2. In the upper right corner, select Fork.

    Screenshot of the Azure-Samples/java-docs-spring-hello-world repo in GitHub, with the Fork option highlighted.

  3. On the Create a new fork screen, confirm the Owner and Repository name fields. Select Create fork.

    Screenshot of the Create a new fork page in GitHub for creating a new fork of Azure-Samples/java-docs-spring-hello-world.

    Note

    This should take you to the new fork. Your fork URL will look something like this: https://github.com/YOUR_GITHUB_ACCOUNT_NAME/java-docs-spring-hello-world

2 - Deploy to Azure

  1. Log in to the Azure portal.

  2. Type app services in the search. Under Services, select App Services.

    Screenshot of the Azure portal with 'app services' typed in the search text box. In the results, the App Services option under Services is highlighted.

  3. In the App Services page, select Create.

    Screenshot of the App Services page in the Azure portal. The Create button in the action bar is highlighted.

  4. Fill out the Create Web App page as follows.

  • Resource Group: Create a resource group named myResourceGroup.
  • Name: Type a globally unique name for your web app.
  • Publish: Select Code.
  • Runtime stack: Select Java 11.
  • Java web-server stack: Select Java SE (Embedded Web Server).
  • Operating system: Select Windows.
  • Region: Select an Azure region close to you.
  • App Service Plan: Create an app service plan named myAppServicePlan.
  1. To change the App Service Plan tier, next to Sku and size, select Change size.

  2. In the Spec Picker, on the Production tab, select P1V3. Select the Apply button at the bottom of the page.

    Screenshot of the Spec Picker for the App Service Plan pricing tiers in the Azure portal. Production, P1V3, and Apply are highlighted.

  3. Select the Deployment section. Under GitHub Actions settings, for Continuous deployment, select Enable.

    Screenshot of the Deployment section of the Create Web App wizard in the Azure portal. Deployment - the second section - is highlighted. Under GitHub Actions settings, continuous deployment's Enable is also highlighted.

  4. In the section under GitHub Actions details, select the following settings:

  • GitHub account: Log in to your GitHub account.
  • Organization: Select your organization.
  • Repository: Select java-docs-spring-hello-world.
  • Branch: Select main.
  1. Select the Review + create button at the bottom of the page.

  2. After validation runs, select the Create button at the bottom of the page. This will create an Azure resource group, app service plan, and app service.

  3. Once the resources are created, select Go to resource. On the created App Service page, select Overview > URL.

    Screenshot of the App Service resource's overview with the URL highlighted.

The Java SE sample code is running in an Azure App Service Linux web app.

Screenshot of the sample app running in Azure, showing 'Hello World!'.

Congratulations! You've deployed your first Java app to App Service using the Azure portal.

3 - Update in GitHub and redeploy the code

  1. Browse to your GitHub fork of java-docs-spring-hello-world.

  2. On your repo page, press . to start Visual Studio Code within your browser.

    Note

    The URL will change from GitHub.com to GitHub.dev. This feature only works with repos that have files. This does not work on empty repos.

    Screenshot of forked GitHub repo with an annotation to Press the period key.

  3. Navigate to src/main/java/com/example/demo/DemoApplication.java.

    Screenshot of Visual Studio Code in the browser, highlighting src/main/java/com/example/demo/DemoApplication.java in the Explorer pane.

  4. Edit the sayHello method so that it shows "Hello Azure!" instead of "Hello World!"

    @RequestMapping("/")
    String sayHello() {
        return "Hello Azure!";
    }
    
  5. From the Source Control pane, select the Stage Changes button to stage the change.

    Screenshot of Visual Studio Code in the browser, highlighting the Source Control navigation in the sidebar, then highlighting the Stage Changes button in the Source Control panel.

  6. Enter a commit message such as Hello Azure. Then, select Commit and Push.

    Screenshot of Visual Studio Code in the browser, Source Control panel with a commit message of 'Hello Azure' and the Commit and Push button highlighted.

  7. Once deployment has completed, return to the browser window that opened during the Browse to the app step, and refresh the page.

    Screenshot of the updated sample app running in Azure, showing 'Hello Azure!'.

4 - Manage your new Azure app

  1. Go to the Azure portal to manage the web app you created. Search for and select App Services.

    Screenshot of the Azure portal with 'app services' typed in the search text box. In the results, the App Services option under Services is highlighted.

  2. Select the name of your Azure app.

    Screenshot of the App Services list in Azure. The name of the demo app service is highlighted.

Your web app's Overview page will be displayed. Here, you can perform basic management tasks like Browse, Stop, Restart, and Delete.

Screenshot of the App Service overview page in Azure portal. In the action bar, the Browse, Stop, Swap (disabled), Restart, and Delete button group is highlighted.

The web app menu provides different options for configuring your app.

5 - Clean up resources

When you're finished with the sample app, you can remove all of the resources for the app from Azure. It will not incur extra charges and keep your Azure subscription uncluttered. Removing the resource group also removes all resources in the resource group and is the fastest way to remove all Azure resources for your app.

  1. From your App Service Overview page, select the resource group you created earlier.

  2. From the resource group page, select Delete resource group. Confirm the name of the resource group to finish deleting the resources.

Next steps