Skip to content

Latest commit

 

History

History
197 lines (124 loc) · 9.85 KB

README.md

File metadata and controls

197 lines (124 loc) · 9.85 KB

JBoss EAP on App Service

This tutorial shows how to deploy JBoss EAP onto Azure App Service. The JBoss app server is deployed as a custom container. This is a technical proof-of-concept to provide feedback for the product roadmap. This container should not be used to host production workloads.

If you run into any problems, please file an issue directly on this repo. Send any feedback or suggestions to [email protected]

Table of Contents

Prerequisites

To complete this tutorial, you will need the following tools installed on your machine.

  • The Azure CLI
  • Maven
  • Docker (optional)
  • An FTP client, such as FileZilla

You will also need an active Azure Subscription.

Tutorial

Create the App Service Plan and resource group

If you do not already have an App Service Plan and resource group created, run the commands below to create them.

az group create --name <resource-group> --location eastus2
az appservice plan create --name <plan-name> --resource-group <resource-group> --sku P1V2 --is-linux

If you would like to use a different region, run the command az account list-locations to see a list of locations.

Create and configure the web app

Now that the App Service Plan is created, we will create a Linux web app on the plan.

  1. Run the Azure CLI command below to create an Azure web app. This command will use jasonfreeberg/jboss-on-app-service as the container image.

    az webapp create -n <webapp-name> -g <resource-group> -p <app-service-plan-name> --deployment-container-image-name "jasonfreeberg/jboss-on-app-service:v1"

    It can take up to 3.5 minutes for the system to pull the image the first time. Subsequent pulls are faster.

  2. Once the webapp is created, run this CLI command to allow the container to use the App Service file system.

    az webapp config appsettings set --name <webapp-name> --resource-group <resource-group> --settings WEBSITES_ENABLE_APP_SERVICE_STORAGE=true

  3. Browse to your web app at http://<webapp-name>.azurewebsites.net. You should see the default JSP. You now have a custom container running JBoss deployed on App Service.

Deploy a WAR file

We will now use App Service's REST APIs to deploy a .WAR file onto the web app.

Build the sample app

From the root directory of the repository, run the following commands to build the sample app. This will use Maven to create a WAR file under sample/target/app.war.

cd sample
mvn clean install

Deploy the sample app

Next, deploy the WAR file using either cURL or PowerShell. After deploying, browse to your web app to confirm the WAR file has deployed.

with cURL

  1. To deploy with cURL, you will need the deployment username and password. Run the command below. In the command output, your username and password are in the first JSON.

    az webapp deployment list-publishing-profiles --name <ap-name> --resource-group <resource-group>

  2. Copy the username and paste it into the placeholder below. Run the cURL command and enter the password when prompted.

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

If have the Azure PowerShell commandlets installed and you are logged in, you can use the following command to deploy (no need to get the deployment credentials).

Publish-AzWebapp -ResourceGroupName <group-name> -Name <app-name> -ArchivePath <war-file-path>

SSH into the web app

This container has been configured to allow easy SSH from the Kudu management site, simply open a browser to https://<app-name>.scm.azurewebsites.net/webssh/host.

You can also connect using you favorite SSH client. For more information, see this article.

Configure JBoss

In App Service, each app instance is stateless. This means any changes applied to the container as it is running will be lost if the instance moves or restarts. App Service allows you to specify a startup script to be called as the container starts. This is where your can specify a shell script to run any JBoss CLI commands (or other commands) to configure the container.

The section below shows how to upload a database driver and use a startup script to register it as a JBoss module.

Configure a database

The db_config/ directory of this repository contains a JDBC driver for Postgres and a shell script to add this driver as a JBoss module. Open startup_script.sh and take a look at the contents.

Use your FTP client to upload the contents of the db_config/ directory to the container's /home/wwwroot/deployments/tools directory. You can use az webapp deployment list-publishing-profiles --name <app-name> --resource-group <group> to get the site's FTP deployment URL, username, and password.

Once the driver and shell script are uploaded, run the following Azure CLI command. This will configure the platform to run the shell script whenever your JBoss container starts.

az webapp config set --startup-file "/home/site/deployments/tools/startup_script.sh" --name <webapp-name> --resource-group <group-name>

Monitor with Application Insights

The container is configured with Application Insights. To view the telemetry, simply create an Application Insights resource and provide your instrumentation key as an environment variable.

  1. Create an Application Insights resource using the Azure Portal.

  2. Create a new app setting, APPINSIGHTS_INSTRUMENTATIONKEY, with your AI Instrumentation key from the Application Insights blade.

    az webapp config appsettings set --name <webapp-name> --resource-group <resource-group> --settings APPINSIGHTS_INSTRUMENTATIONKEY=<your-key>

You can now use Application Insights to set up alerts, query metrics, or send custom telemetry.

Outsource application state

JBoss applications are sometimes run in a clustered configuration (also known as domain mode). However, App Service does not support direct communication between application instances so JBoss apps can only be run in standalone mode on App Service. If you do wish to run a stateful JBoss EAP application on the platform, the state must be stored remotely in Red Hat Data Grid. JBoss 7 supports For more information, please see this section of the JBoss 7 docs.

If you are migrating an existing JBoss application that runs in domain mode, see JBoss on Azure Virtual Machines.

Local Usage

The following instructions are for using the Docker image locally. These steps are not required to run the image on App Service.

Build and run the container

  1. Build the image.
docker build . -t jboss --build-arg RH_USERNAME --build-arg RH_PASSWORD
  1. Run the image. This will mount a directory to the wwwroot directory, so we can deploy WAR applications locally.
docker run --name jboss --env APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=1e5607a2-dbac-4527-887a-102cbe2bdefa -v ~/mounted_home:/home/ --publish-all jboss
  1. Get the port mapping
docker container ps

This will show the jboss container under the PORTS column.

  1. Open a browser to http://localhost:<port-mapped-to-8080>

SSH into the container

docker exec -it jboss bash

Related Materials

  • "The JBoss EAP management CLI is not recommended for use with JBoss EAP running in a containerized environment. Any configuration changes made using the management CLI in a running container will be lost when the container restarts." Source
  • The container image used in this tutorial is based on the JBoss EAP 7.2 for OpenShift Container Image