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

• An Azure account with an active subscription. If you don't have an Azure account, you can create an account.
• 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 trial is available.

• An Azure account with an active subscription. If you don't have an Azure account, you can create one for free.
• Azure Developer CLI installed. You can follow the steps with the Azure Cloud Shell because it already has Azure Developer CLI installed.
• Knowledge of Java with Spring Framework development.
• (Optional) To try GitHub Copilot, a GitHub Copilot account. A 30-day trial is available.

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 in the form of https://<app-name>-<hash>.<region>.chinacloudsites.cn.
• 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.

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 key vault and change your app setting to a Key Vault reference with the help of Service Connectors.

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.

Like the Tomcat convention, if you want to deploy to the root context of Tomcat, name your built artifact ROOT.war.

Having issues? Check the Troubleshooting section.

5. Browse to the app

Having issues? Check the Troubleshooting section.

6. Stream diagnostic logs

Azure App Service captures all messages output to the console to help you diagnose issues with your application. The sample application includes standard Log4j logging statements to demonstrate this capability, as shown in the following snippet:

    private static Logger logger = LoggerFactory.getLogger(TodoListController.class);

    @Autowired
    private TodoItemRepository todoItemRepository;

    public TodoListController() {
    }

    /**
     * HTTP GET
     */
    @GetMapping(path = "/api/todolist/{index}", produces = {MediaType.APPLICATION_JSON_VALUE})
    public TodoItem getTodoItem(@PathVariable("index") String index) {
        logger.info("GET request access '/api/todolist/{}' path.", index);
        return todoItemRepository.findById(index).get();
    }

Learn more about logging in Java apps in the series on Enable Azure Monitor OpenTelemetry for .NET, Node.js, Python and Java applications.

Having issues? Check the Troubleshooting section.

7. Clean up resources

When you're finished, you can delete all of the resources from your Azure subscription by deleting the resource group.

2. Create Azure resources and deploy a sample app

In this step, you create the Azure resources and deploy a sample app to App Service on Linux. The steps used in this tutorial create a set of secure-by-default resources that include App Service and Azure Cosmos DB.

The dev container already has the Azure Developer CLI (AZD).

1. From the repository root, run azd init.

   azd init --template javase-app-service-cosmos-redis-infra
   

2. When prompted, give the following answers:

   Question	Answer
   The current directory is not empty. Would you like to initialize a project here in '<your-directory>'?	Y
   What would you like to do with these files?	Keep my existing files unchanged
   Enter a new environment name	Type a unique name. The AZD template uses this name as part of the DNS name of your web app in Azure (<app-name>-<hash>.chinacloudsites.cn). Alphanumeric characters and hyphens are allowed.

3. Sign into Azure by running the azd auth login command and following the prompt:

   azd auth login
   

4. Create the necessary Azure resources and deploy the app code with the azd up command. Follow the prompt to select the desired subscription and location for the Azure resources.

   azd up
   

   The azd up command takes about 15 minutes to complete (the Redis cache takes the most time). It also compiles and deploys your application code, but you'll modify your code later to work with App Service. While it's running, the command provides messages about the provisioning and deployment process, including a link to the deployment in Azure. When it finishes, the command also displays a link to the deploy application.

   This AZD template contains files (azure.yaml and the infra directory) that generate a secure-by-default architecture with the following Azure resources:

   • Resource group: The container for all the created resources.
   • App Service plan: Defines the compute resources for App Service. A Linux plan in the B1 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 account with MongoDB API: Accessible only from behind its private endpoint. A database is created for you on the server.
   • Azure Cache for Redis: Accessible only from within the virtual network.
   • Key vault: Accessible only from behind its private endpoint. Used to manage secrets for the App Service app.
   • Private endpoints: Access endpoints for the key vault, the database server, and the Redis cache in the virtual network.
   • Private DNS zones: Enable DNS resolution of the Cosmos DB database, the Redis cache, and the key vault in the virtual network.
   • Log Analytics workspace: Acts as the target container for your app to ship its logs, where you can also query the logs.

Having issues? Check the Troubleshooting section.

3. Verify connection strings

The AZD template you use generated the connectivity variables for you already as app settings and outputs the them to the terminal for your convenience. App settings are one way to keep connection secrets out of your code repository.

1. In the AZD output, find the app setting spring.data.mongodb.uri. Only the setting names are displayed. They look like this in the AZD output:

    App Service app has the following app settings:
            - spring.data.mongodb.uri
            - spring.data.mongodb.database
            - spring.redis.host
            - spring.redis.port
            - spring.redis.password
            - spring.redis.database
            - spring.redis.ssl
            - spring.cloud.azure.keyvault.secret.credential.managed_identity_enabled
            - spring.cloud.azure.keyvault.secret.endpoint
            - azure.keyvault.uri
            - azure.keyvault.scope
    

   spring.data.mongodb.uri contains the connection URI to the Cosmos DB database in Azure. It's a standard Spring Data variable, which your application is already using in the src/main/resources/application.properties file.

2. In the explorer, navigate to src/main/resources/application.properties and see that your Spring Boot app is already using the spring.data.mongodb.uri variable to access data.

3. For your convenience, the AZD template output shows you the direct link to the app's app settings page. Find the link and open it in a new browser tab.

   If you look at the value of spring.data.mongodb.uri, it should be @Microsoft.KeyValut(...), which means that it's a key vault reference because the secret is managed in the key vault.

Having issues? Check the Troubleshooting section.

4. Browse to the app

1. In the AZD output, find the URL of your app and navigate to it in the browser. The URL looks like this in the AZD output:

    Deploying services (azd deploy)
   
      (✓) Done: Deploying service web
      - Endpoint: https://<app-name>-<hash>.chinacloudsites.cn/
    

2. Add a few tasks to the list.

   

   Congratulations, you're running a web app in Azure App Service, with secure connectivity to Azure Cosmos DB.

Having issues? Check the Troubleshooting section.

5. Stream diagnostic logs

Azure App Service can capture console logs to help you diagnose issues with your application. For convenience, the AZD template already enabled logging to the local file system and is shipping the logs to a Log Analytics workspace.

The sample application includes standard Log4j logging statements to demonstrate this capability, as shown in the following snippet:

    private static Logger logger = LoggerFactory.getLogger(TodoListController.class);

    @Autowired
    private TodoItemRepository todoItemRepository;

    public TodoListController() {
    }

    /**
     * HTTP GET
     */
    @GetMapping(path = "/api/todolist/{index}", produces = {MediaType.APPLICATION_JSON_VALUE})
    public TodoItem getTodoItem(@PathVariable("index") String index) {
        logger.info("GET request access '/api/todolist/{}' path.", index);
        return todoItemRepository.findById(index).get();
    }

In the AZD output, find the link to stream App Service logs and navigate to it in the browser. The link looks like this in the AZD output:

Stream App Service logs at: https://portal.azure.cn/#@/resource/subscriptions/<subscription-guid>/resourceGroups/<group-name>/providers/Microsoft.Web/sites/<app-name>/logStream

Learn more about logging in Java apps in the series on Enable Azure Monitor OpenTelemetry for .NET, Node.js, Python and Java applications.

Having issues? Check the Troubleshooting section.

6. Clean up resources

To delete all Azure resources in the current deployment environment, run azd down and follow the prompts.

azd down