Luimoll / jboss-on-app-service

A tutorial for using JBoss EAP on Azure App Service

JBoss EAP on App Service demo

In this tutorial you will create a JBoss EAP 7.2 instance on Azure App Service. Once the site is created, you will deploy a demo app and configure the JBoss server to communicate with PostgreSQL.

Have feedback for us? Email us!

Prerequisites

To follow this tutorial, you will need...

• Java 8 installed locally
• Maven installed locally
• An Azure subscription

Tutorial

This tutorial will walk through the process of creating a JBoss EAP site on App Service, deploying a WAR application, and configuring the JBoss EAP server to connect to a PostgreSQL database.

Create a JBoss EAP site

1. Open to the Azure Portal to the Web App create blade. For Runtime stack, select JBoss EAP 7.2 (Preview). JBoss EAP sites can only be created on Premium and Isolated App Service Plans (more information).

2. Once the site is created, browse to the site and you should see the default (aka "parking") page.

3. Open a terminal and clone the Pet Store demo application. We will deploy this app onto the JBoss EAP App Service.

   git clone https://github.com/agoncal/agoncal-application-petstore-ee7.git

4. Build the WAR file with mvn clean install -DskipTests.

5. Deploy the war file to your web app. First, change directories into the sample project, cd agoncal-application-petstore-ee7.

   Powershell

   Publish-AzWebapp -ResourceGroupName <group-name> -Name <app-name> -ArchivePath agoncal-application-petstore-ee7\target\applicationPetstore.war

   Bash

   For bash, you will need to copy the username and password from your app's publishing credentials.

   curl -X POST -u <username> --data-binary @"<war-file-path>" https://<app-name>.scm.azurewebsites.net/api/wardeploy

6. Browse to your web app and confirm that the app is now running. This app is using an in-memory H2 database by default. Let's now create a PostgreSQL database and connect it to the application.

Create a PostgreSQL server and database

1. Run the following command to create a Azure Database for PostgreSQL server.

   az postgres server create --resource-group <group-name> --name mydemoserver --location westus --admin-user myadmin --admin-password <server_admin_password> --sku-name GP_Gen5_2

2. In the "Connection security" panel of the Azure Database blade, toggle the "Allow access to Azure services" button to the "ON" position. Alternatively, you can run the following CLI command.

    az postgres server firewall-rule create -g <group-name> -s <server-name> -n AllowAllWindowsAzureIps --start-ip-address 0.0.0.0 --end-ip-address 0.0.0.0 

Configure JBoss EAP for PostgreSQL

1. Next, we need to edit our Java Transaction API configuration so that our Java application will communicate with Postgres instead of the in-memory H2 database we were using previously. Open an editor to src/main/resources/META-INF/persistence.xml. Replace the value for <jta-data-source> with java:jboss/datasources/postgresDS. Your JTA XML should now have this setting:

   <jta-data-source>java:jboss/datasources/postgresDS</jta-data-source>

2. Create three app settings on the site:

   • POSTGRES_CONNECTION_URL: The connection URL for the server, the format should look like jdbc:postgresql://freebergserver123.postgres.database.azure.com:5432/petstore?ssl=true.
   • POSTGRES_SERVER_ADMIN_FULL_NAME: The username for the server (provided in the previous command)
   • POSTGRES_SERVER_ADMIN_PASSWORD: The password for the server (provided in the previous command)

3. Before deploying our reconfigured application, we must update the JBoss application server with the Postgres module and its dependencies. To configure the server we will need the four files in the db_config/ directory:

   • postgresql-42.2.12.jar: This .jar is the JDBC driver for Postgres. For more information, please see the official website.
   • postgres-module.xml: This XML file declares a name for the Postgres module (org.postgres). It also specifies the resources and dependencies necessary for the module to be used.
   • startup_script.sh: Finally, this shell script will be executed whenever your App Service instance is started. The script runs the JBoss CLI commands to configure the server with the data source module, driver, and expose the JNDI name.
   • jboss-cli-commands.cli: The JBoss CLI commands that will be executed by the startup script.

4. Using an FTP tool of your choice transfer database driver, XML module descriptor, and cli commands to /home/site/deployments/tools/. Upload the startup script to the /home/ path as /home/startup.sh. App Service will automatically run the startup script if it follows that naming convention.

5. Restart the web app. This will cause the web app to run the configuration script.

6. Update persistence.xml

   ...
       <jta-data-source>java:jboss/datasources/postgresDS</jta-data-source>
   ...

7. Repackage and redeploy using the CLI commands below.

   PowerShell

   mvn clean install -DskipTests
   Publish-AzWebapp -ResourceGroupName <group-name> -Name <app-name> -ArchivePath agoncal-application-petstore-ee7\target\applicationPetstore.war

   Bash

   mvn clean install -DskipTests
   curl -X POST -u <username> --data-binary @"<war-file-path>" https://<app-name>.scm.azurewebsites.net/api/wardeploy

8. Finally, browse to the web app. The pet store app is configured such that if it cannot connect to Postgres, then it will not start. So if you can see and interact with the Petstore application, then you have successfully completed the tutorial! See the resources below for more info. If you got stuck, please file an issue.

Resources

• Petstore Application
• Quickstart for Azure PostgreSQL
• Old quickstart for Wildfly
• JBoss CLI official documentation