Edit

Tutorial: Build a Java Spring Boot web app with Azure App Service on Linux and Azure Cosmos DB

In this tutorial, you learn how to build, configure, and deploy a secure Spring Boot application in Azure App Service that connects to a MongoDB database in Azure (actually, a Cosmos DB database with MongoDB API). When you're finished, you'll have a Java SE application running on Azure App Service on Linux.

Screenshot of Spring Boot application storing data in Cosmos DB.

In this tutorial, you learn how to:

  • Create a secure-by-default architecture for Azure App Service and Azure Cosmos DB with MongoDB API.
  • Secure connection secrets using a managed identity and Key Vault references.
  • Deploy a Spring Boot sample app to App Service from a GitHub repository.
  • Access App Service app settings in the application code.
  • Make updates and redeploy the application code.
  • Stream diagnostic logs from App Service.
  • Manage the app in the Azure portal.
  • Provision the same architecture and deploy by using Azure Developer CLI.
  • Optimize your development workflow with GitHub Codespaces and GitHub Copilot.

Prerequisites

  • An Azure account with an active subscription. If you don't have an Azure account, you can create one for free.
  • A GitHub account. you can also get one for free.
  • Knowledge of Java with Spring Framework development.
  • (Optional) To try GitHub Copilot, a GitHub Copilot account. A 30-day free trial is available.

Skip to the end

You can quickly deploy the sample app in this tutorial and see it running in Azure. Just run the following commands in the Azure Cloud Shell, and follow the prompt:

mkdir msdocs-spring-boot-mongodb-sample-app
cd msdocs-spring-boot-mongodb-sample-app
azd init --template msdocs-spring-boot-mongodb-sample-app .
azd up

1. Run the sample

First, you set up a sample data-driven app as a starting point. For your convenience, the sample repository, includes a dev container configuration. The dev container has everything you need to develop an application, including the MongoDB database, cache, and all environment variables needed by the sample application. The dev container can run in a GitHub codespace, which means you can run the sample on any computer with a web browser.

Step 1: In a new browser window:

  1. Sign in to your GitHub account.
  2. Navigate to https://github.com/Azure-Samples/msdocs-spring-boot-mongodb-sample-app/fork.
  3. Unselect Copy the main branch only. You want all the branches.
  4. Select Create fork.

A screenshot showing how to create a fork of the sample GitHub repository.

Step 2: In the GitHub fork:

  1. Select main > starter-no-infra for the starter branch. This branch contains just the sample project and no Azure-related files or configuration.
  2. Select Code > Create codespace on starter-no-infra. The codespace takes a few minutes to set up.

A screenshot showing how to create a codespace in GitHub.

Step 3: In the codespace terminal:

  1. Run mvn package spring-boot:run.
  2. When you see the notification Your application running on port 8080 is available., select Open in Browser. You should see the sample application in a new browser tab. To stop the Jetty server, type Ctrl+C.

A screenshot showing how to run the sample application inside the GitHub codespace.

Tip

You can ask GitHub Copilot about this repository. For example:

  • @workspace What does this project do?
  • @workspace How does the app connect to the database?
  • @workspace What does the .devcontainer folder do?

Having issues? Check the Troubleshooting section.

2. Create App Service and Cosmos DB

First, you create the Azure resources. The steps used in this tutorial create a set of secure-by-default resources that include App Service and Azure Cosmos DB. For the creation process, you specify:

  • The Name for the web app. It's used as part of the DNS name for your app.
  • The Region to run the app physically in the world. It's also used as part of the DNS name for your app.
  • The Runtime stack for the app. It's where you select the version of Java to use for your app.
  • The Hosting plan for the app. It's the pricing tier that includes the set of features and scaling capacity for your app.
  • The Resource Group for the app. A resource group lets you group (in a logical container) all the Azure resources needed for the application.

Sign in to the Azure portal and follow these steps to create your Azure App Service resources.

  1. In the Azure portal:

    • In the search bar at the top, enter app service.
    • Under the Services heading, select App Service.
    • Select Create > Web App.

    You can also go directly to the creation wizard.

  2. In the Create Web App page, on the Basics tab, fill out the form as follows:

    • Resource Group: Select Create new and use a name of msdocs-spring-cosmosdb-tutorial.
    • Name: msdocs-spring-cosmosdb-XYZ where XYZ is any three random characters. This name must be unique across Azure.
    • Runtime stack: Java 25.
    • Java web server stack: Java SE (Embedded Web Server).
    • Operating System: Linux.
    • Region: Any Azure region near you.
    • Pricing plan: Basic. When you're ready, you can scale up to a production pricing tier.

  3. Select the Database tab and configure the database:

    • Select Create a Database.
    • In Engine, select Cosmos DB API for MongoDB. Cosmos DB is a fully managed NoSQL, relational, and vector database as a service on Azure.
    • Don't select Create an Azure Cache for Redis.

  4. Select Review + create. After validation completes, select Create.

  5. When deployment finishes, select the Go to resource button. You're taken directly to the App Service app.

The following resources are created:

  • Resource group: The container for all the created resources.
  • App Service plan: Defines the compute resources for App Service. A Linux plan in the Basic tier is created.
  • App Service: Represents your app and runs in the App Service plan.
  • Virtual network: Integrated with the App Service app and isolates back-end network traffic.
  • Azure Cosmos DB: Accessible only from behind its private endpoint. A database is created for you on the database account.
  • Private endpoints: Access endpoints for the database server in the virtual network.
  • Private DNS zones: Enable DNS resolution of the database server in the virtual network.

Having issues? Check the Troubleshooting section.

3. Secure connection secrets

The creation wizard generated the connectivity string for you already as an app setting. However, the security best practice is to keep secrets out of App Service completely. You'll move your secrets to a key vault and change your app setting to a Key Vault reference with the help of Service Connectors.

Step 1: In the App Service page:

  1. In the left menu, select Settings > Environment variables.
  2. Next to AZURE_COSMOS_CONNECTIONSTRING, select Show value. This connection string lets you connect to the Cosmos DB database secured behind a private endpoint. However, the secret is saved directly in the App Service app, which isn't the best. You'll change this.

A screenshot showing how to see the value of an app setting.

Step 2: Create a key vault for secure management of secrets.

  1. In the top search bar, type "key vault", then select Marketplace > Key Vault.
  2. In Resource Group, select msdocs-spring-cosmosdb-tutorial.
  3. In Key vault name, type a name that consists of only letters and numbers.
  4. In Region, set it to the sample location as the resource group.

A screenshot showing how to create a key vault.

Step 3:

  1. Select the Networking tab.
  2. Unselect Enable public access.
  3. Select Create a private endpoint.
  4. In Resource Group, select msdocs-spring-cosmosdb-tutorial.
  5. In Key vault name, type a name that consists of only letters and numbers.
  6. In Region, set it to the sample location as the resource group.
  7. In the dialog, in Location, select the same location as your App Service app.
  8. In Resource Group, select msdocs-spring-cosmosdb-tutorial.
  9. In Name, type msdocs-spring-cosmosdb-XYZVaultEndpoint.
  10. In Virtual network, select msdocs-spring-cosmosdb-XYZVnet.
  11. In Subnet, msdocs-spring-cosmosdb-XYZSubnet.
  12. Select OK.
  13. Select Review + create, then select Create. Wait for the key vault deployment to finish. You should see "Your deployment is complete."

A screenshot showing how to secure a key vault with a private endpoint.

Step 4:

  1. In the top search bar, type msdocs-spring-cosmosdb, then the App Service resource called msdocs-spring-cosmosdb-XYZ.
  2. In the App Service page, in the left menu, select Settings > Service Connector. There's already a connector, which the app creation wizard created for you.
  3. Select checkbox next to the connector, then select Edit.
  4. In the Basics tab, set Client type to SpringBoot. This option creates the Spring Boot specific environment variables for you.
  5. Select the Authentication tab.
  6. Select Store Secret in Key Vault.
  7. Under Key Vault Connection, select Create new. A Create connection dialog is opened on top of the edit dialog.

A screenshot showing how to edit a service connector with a key vault connection.

Step 5: In the Create connection dialog for the Key Vault connection:

  1. In Key Vault, select the key vault you created earlier.
  2. Select Review + Create. You should see that System assigned managed identity is set to Selected.
  3. When validation completes, select Create.

A screenshot showing how to configure a key vault service connector.

Step 6: You're back in the edit dialog for defaultConnector.

  1. In the Authentication tab, wait for the key vault connector to be created. When it's finished, the Key Vault Connection dropdown automatically selects it.
  2. Select Next: Networking.
  3. Select Configure firewall rules to enable access to target service. If you see the message, "No Private Endpoint on the target service," ignore it. The app creation wizard already secured the Cosmos DB database with a private endpoint.
  4. Select Save. Wait until the Update succeeded notification appears.

A screenshot showing the key vault connection selected in the defaultConnector.

Step 7: To verify your changes:

  1. From the left menu, select Environment variables again.
  2. Make sure that the app setting spring.data.mongodb.uri exists. The default connector generated it for you, and your Spring Boot application already uses the variable.
  3. Next to the app setting, select Show value. The value should be @Microsoft.KeyVault(...), which means that it's a key vault reference because the secret is now managed in the key vault.

A screenshot showing how to see the value of the Spring Boot environment variable in Azure.

Having issues? Check the Troubleshooting section.

4. Deploy sample code

In this step, you configure GitHub deployment using GitHub Actions. It's just one of many ways to deploy to App Service, but also a great way to have continuous integration in your deployment process. By default, every git push to your GitHub repository kicks off the build and deploy action.

Step 1: In the left menu, select Deployment > Deployment Center.

A screenshot showing how to open the deployment center in App Service.

Step 2: In the Deployment Center page:

  1. In Source, select GitHub. By default, GitHub Actions is selected as the build provider.
  2. Sign in to your GitHub account and follow the prompt to authorize Azure.
  3. In Organization, select your account.
  4. In Repository, select msdocs-spring-boot-mongodb-sample-app.
  5. In Branch, select starter-no-infra. This is the same branch that you worked in with your sample app, without any Azure-related files or configuration.
  6. For Authentication type, select User-assigned identity.
  7. In the top menu, select Save. App Service commits a workflow file into the chosen GitHub repository, in the .github/workflows directory. By default, the deployment center creates a user-assigned identity for the workflow to authenticate using Microsoft Entra (OIDC authentication). For alternative authentication options, see Deploy to App Service using GitHub Actions.

A screenshot showing how to configure CI/CD using GitHub Actions.

Step 3:

  1. Select the Logs tab. See that a new deployment already ran, but the status is Failed.
  2. Select Build/Deploy Logs. A browser tab opens to the Actions tab of your forked repository in GitHub. In Annotations, you see the error The string 'java25' is not valid SemVer notation for a Java version. If you want, select the failed build step in the page to get more information.

A screenshot showing an error in the deployment center's Logs page.

Step 4: The error shows that something went wrong during the GitHub workflow. To fix it, pull the latest changes into your codespace first. Back in the GitHub codespace of your sample fork, run git pull origin starter-no-infra. This pulls the newly committed workflow file into your codespace.

A screenshot showing git pull inside a GitHub codespace.

Step 5 (Option 1: with GitHub Copilot):

  1. Start a new chat session by selecting the Chat view, then selecting +.
  2. Ask, "@workspace Why do I get the error in GitHub actions: The string 'java25' is not valid SemVer notation for a Java version." Copilot might give you an explanation and even give you the link to the workflow file that you need to fix.
  3. Open .github/workflows/starter-no-infra_msdocs-spring-cosmosdb-123.yaml in the explorer and make the suggested fix. GitHub Copilot doesn't give you the same response every time, you might need to ask more questions to fine-tune its response. For tips, see What can I do with GitHub Copilot in my codespace?.