Tutorial: Build a Quarkus web app with Azure App Service on Linux and PostgreSQL

Article
11/30/2023

This tutorial shows how to build, configure, and deploy a secure Quarkus application in Azure App Service that's connected to a PostgreSQL database (using Azure Database for PostgreSQL). Azure App Service is a highly scalable, self-patching, web-hosting service that can easily deploy apps on Windows or Linux. When you're finished, you'll have a Quarkus app running on Azure App Service on Linux.

Screenshot of Quarkus application storing data in PostgreSQL.

To complete this tutorial, you'll need:

An Azure account with an active subscription. If you don't have an Azure account, you can create one for free.
Knowledge of Java with Quarkus development.

1. Run the sample

For your convenience, the sample repository, Hibernate ORM with Panache and RESTEasy, includes a dev container configuration. The dev container has everything you need to develop an application, including the 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:

Sign in to your GitHub account.
Navigate to https://github.com/Azure-Samples/msdocs-quarkus-postgresql-sample-app.
Select Fork.
Select Create fork.

Step 2: In the GitHub fork, select Code > Create codespace on main.

Step 3: In the codespace terminal:

Run mvn quarkus:dev.
When you see the notification Your application running on port 8080 is available., select Open in Browser. If you see a notification with port 5005, skip it. You should see the sample application in a new browser tab. To stop the Quarkus development server, type Ctrl+C.

For more information on how the Quarkus sample application is created, see Quarkus documentation Simplified Hibernate ORM with Panache and Configure data sources in Quarkus.

2. Create App Service and PostgreSQL

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 Database for PostgreSQL. For the creation process, you'll specify:

The Name for the web app. It's the name used as part of the DNS name for your webapp in the form of https://<app-name>.azurewebsites.net.
The Region to run the app physically in the world.
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.

Step 1: In the Azure portal:

Enter "web app database" in the search bar at the top of the Azure portal.
Select the item labeled Web App + Database under the Marketplace heading. You can also navigate to the creation wizard directly.

Step 2: In the Create Web App + Database page, fill out the form as follows.

Resource Group → Select Create new and use a name of msdocs-quarkus-postgres-tutorial.
Region → Any Azure region near you.
Name → msdocs-quarkus-postgres-XYZ where XYZ is any three random characters. This name must be unique across Azure.
Runtime stack → Java 17.
Java web server stack → Java SE (Embedded Web Server).
Database → PostgreSQL - Flexible Server. The server name and database name are set by default to appropriate values.
Hosting plan → Basic. When you're ready, you can scale up to a production pricing tier later.
Select Review + create.
After validation completes, select Create.

Step 3: The deployment takes a few minutes to complete. Once deployment completes, select the Go to resource button. You're taken directly to the App Service app, but 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 Database for PostgreSQL flexible server → Accessible only from within the virtual network. A database and a user are created for you on the server.
Private DNS zone → Enables DNS resolution of the PostgreSQL server in the virtual network.

3. Verify connection settings

The creation wizard generated the connectivity variables for you already as app settings. App settings are one way to keep connection secrets out of your code repository. When you're ready to move your secrets to a more secure location, you can use Key Vault references instead.

Step 1: In the App Service page, in the left menu, select Configuration.

Step 2: In the Application settings tab of the Configuration page, verify that AZURE_POSTGRESQL_CONNECTIONSTRING is present. It's injected at runtime as an environment variable.

Step 4: In the Application settings tab of the Configuration page, select New application setting. Name the setting PORT and set its value to 8080, which is the default port of the Quarkus application. Select OK.

Step 5: Select Save.

Having issues? Check the Troubleshooting section.

4. Deploy sample code

In this step, you'll 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 will kick off the build and deploy action.

Note the following:

Your deployed Java package must be an Uber-Jar.
For simplicity of the tutorial, you'll disable tests during the deployment process. The GitHub Actions runners don't have access to the PostgreSQL database in Azure, so any integration tests that require database access will fail, such as is the case with the Quarkus sample application.

Step 1: Back in the App Service page, in the left menu, select Deployment Center.

Step 2: In the Deployment Center page:

In Source, select GitHub. By default, GitHub Actions is selected as the build provider.
Sign in to your GitHub account and follow the prompt to authorize Azure.
In Organization, select your account.
In Repository, select msdocs-quarkus-postgresql-sample-app.
In Branch, select main.
In Authentication type, select User-assigned identity (Preview).
In the top menu, select Save. App Service commits a workflow file into the chosen GitHub repository, in the .github/workflows directory.

Step 3: Back in the GitHub codespace of your sample fork, run git pull origin main. This pulls the newly committed workflow file into your codespace.

Step 4:

Open src/main/resources/application.properties in the explorer. Quarkus uses this file to load Java properties.
Add a production property %prod.quarkus.datasource.jdbc.url=${AZURE_POSTGRESQL_CONNECTIONTRING}. This property sets the production data source URL to the app setting that the creation wizard generated for you.

Step 5:

Open .github/workflows/main_msdocs-quarkus-postgres-XYZ.yml in the explorer. This file was created by the App Service create wizard.
Under the Build with Maven step, change the Maven command to mvn clean install -DskipTests -Dquarkus.package.type=uber-jar. -DskipTests skips the tests in your Quarkus project, and -Dquarkus.package.type=uber-jar creates an Uber-Jar that App Service needs.

Step 6:

Select the Source Control extension.
In the textbox, type a commit message like Configure DB and deployment workflow.
Select Commit, then confirm with Yes.
Select Sync changes 2, then confirm with OK.

Step 7: Back in the Deployment Center page in the Azure portal:

Select Logs. A new deployment run is already started from your committed changes.
In the log item for the deployment run, select the Build/Deploy Logs entry with the latest timestamp.

Step 8: You're taken to your GitHub repository and see that the GitHub action is running. The workflow file defines two separate stages, build and deploy. Wait for the GitHub run to show a status of Complete. It takes about 5 minutes.

Having issues? Check the Troubleshooting section.

5. Browse to the app

Step 1: In the App Service page:

From the left menu, select Overview.
Select the URL of your app. You can also navigate directly to https://<app-name>.azurewebsites.net.

Step 2: Add a few fruits to the list. Congratulations, you're running a web app in Azure App Service, with secure connectivity to Azure Database for PostgreSQL.

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 JBoss logging statements to demonstrate this capability as shown below.

private static final Logger LOGGER = Logger.getLogger(FruitEntityResource.class.getName());

@GET
public List<FruitEntity> get() {
    LOGGER.info("In FruitEntityResource.get()");
    return FruitEntity.listAll(Sort.by("name"));
}

Step 1: In the App Service page:

From the left menu, select App Service logs.
Under Application logging, select File System.
In the top menu, select Save.

Step 2: From the left menu, select Log stream. You see the logs for your app, including platform logs and logs from inside the container.

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

7. Clean up resources

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

Step 1: In the search bar at the top of the Azure portal:

Enter the resource group name.
Select the resource group.

Step 2: In the resource group page, select Delete resource group.

Step 3:

Enter the resource group name to confirm your deletion.
Select Delete.
Confirm with Delete again.

Troubleshooting

I see the error log "ERROR [org.acm.hib.orm.pan.ent.FruitEntityResource] (vert.x-eventloop-thread-0) Failed to handle request: jakarta.ws.rs.NotFoundException: HTTP 404 Not Found".

This is a Vert.x error (see Quarkus Reactive Architecture), indicating that the client requested an unknown path. This error happens on every app startup because App Service verifies that the app starts by sending a GET request to /robots933456.txt.

The app failed to start and shows the following error in log: "Model classes are defined for the default persistence unit <default> but configured datasource <default> not found: the default EntityManagerFactory will not be created."

This Quarkus error is most likely because the app can't connect to the Azure database. Make sure that the app setting AZURE_POSTGRESQL_CONNECTIONSTRING hasn't been changed, and that application.properties is using the app setting properly.

Frequently asked questions

How much does this setup cost?
How do I connect to the PostgreSQL server that's secured behind the virtual network with other tools?
How does local app development work with GitHub Actions?
What if I want to run tests with PostgreSQL during the GitHub workflow?

How much does this setup cost?

Pricing for the created resources is as follows:

The App Service plan is created in Basic tier and can be scaled up or down. See App Service pricing.
The PostgreSQL flexible server is created in the lowest burstable tier Standard_B1ms, with the minimum storage size, which can be scaled up or down. See Azure Database for PostgreSQL pricing.
The virtual network doesn't incur a charge unless you configure extra functionality, such as peering. See Azure Virtual Network pricing.
The private DNS zone incurs a small charge. See Azure DNS pricing.

How do I connect to the PostgreSQL server that's secured behind the virtual network with other tools?

For basic access from a command-line tool, you can run psql from the app's SSH terminal.
To connect from a desktop tool, your machine must be within the virtual network. For example, it could be an Azure VM in one of the subnets, or a machine in an on-premises network that has a site-to-site VPN connection with the Azure virtual network.
You can also integrate Azure Cloud Shell with the virtual network.

How does local app development work with GitHub Actions?

Using the autogenerated workflow file from App Service as an example, each git push kicks off a new build and deployment run. From a local clone of the GitHub repository, you make the desired updates and push to GitHub. For example:

git add .
git commit -m "<some-message>"
git push origin main

What if I want to run tests with PostgreSQL during the GitHub workflow?

The default Quarkus sample application includes tests with database connectivity. To avoid connection errors, you added the -skipTests property. If you want, you can run the tests against a PostgreSQL service container. For example, in the automatically generated workflow file in your GitHub fork (.github/workflows/main_cephalin-quarkus.yml), make the following changes:

Add YAML code for the PostgreSQL container to the build job, as shown in the following snippet.

...
jobs:
  build:
    runs-on: ubuntu-latest

    # BEGIN CODE ADDITION
    container: ubuntu
    services:
      # Hostname for the PostgreSQL container
      postgresdb:
        image: postgres
        env:
          POSTGRES_PASSWORD: postgres
          POSTGRES_USER: postgres
          POSTGRES_DB: postgres
        # Set health checks to wait until postgres has started
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    # END CODE ADDITION

    steps:
      - uses: actions/checkout@v4
      ...

container: ubuntu tells GitHub to run the build job in a container. This way, the connection string in your dev environment jdbc:postgresql://postgresdb:5432/postgres can work as-is in when the workflow runs. For more information about PostgreSQL connectivity in GitHub Actions, see Creating PostgreSQL service containers.

In the Build with Maven step, remove -DskipTests. For example:

      - name: Build with Maven
        run: mvn clean install -Dquarkus.package.type=uber-jar

Next steps

Learn more about running Java apps on App Service in the developer guide.

Configure a Java app in Azure App Service

Learn how to secure your app with a custom domain and certificate.

Secure with custom domain and certificate