TomEE on Azure cloud

If you have an application on TomEE and want to deploy it on Microsoft’s Azure cloud, then this blog post is for you. Once everything is configured, the build and the deployment will require only a single command line and you will be able to access the application from anywhere in the World!

Downloading TomEE-Azure Module

We have already prepared a TomEE/Azure module ( cloud-tomee-azure module found in the TomEE examples) to make working with TomEE in Azure much easier.

To take advantage of this module, you will first need to checkout TomEE from Github:

git clone [email protected]:apache/tomee.git

Then, navigate to the the cloud-tomee-azure module:

cd tomee/examples/cloud-tomee-azure

Azure Setup

You will need to setup your Azure account and add a subscription

• Create an Azure Account, if you don’t have one, go to the Azure web site ( https://azure.microsoft.com/en-us). Make sure you select the free option and then follow the instructions to set up your account.
• Login to your Azure Account and add a subscription. I chose Pay-As-You-Go because it seemed the cheapest for this experiment.
• Install the Azure (CLI) according to the operating system of the computer you are using. The CLI will enable us to interact with Azure using the command line.
• There is a Workaround for a JAVA_HOME bug on Azure that you will need to apply in order to successfully deploy your example. Please check the related section at the bottom of the article.

Configure your local machine

Configuration requires logging into Azure, registering a new App Service and getting the relevant IDs for use with Maven’s settings.xml. Configuration only needs to be done once per app. While it is possible to deploy using only the Azure CLI, I find that using Maven is simpler, as it requires you to remember fewer details.

Login with the Azure CLI:

Once you’ve installed the Azure CLI you can use it to log in to your Azure Account by executing:

$ az login

After a successful login you are presented with the following JSON output:

[
   {
 	"cloudName": "AzureCloud",
 	"id": "aaaaaaaa-aaaa-aaaa-aaaaa-aaaaaaaaaa",
 	"isDefault": true,
 	"name": "Pay-As-You-Go",
 	"state": "Enabled",
 	"tenantId": "bbbbbbb-bbbbb-bbbb-bbbbb-bbbbbbbbbbb",
 	"user": {
   	"name": "",
   	"type": "user"
 	}
   }
 ]

The TenantId is the person that can register and manage apps – in this case, yourself. You will need that for later so copy and save it where you can get to it again.

Create an Azure Principal

An Azure service principal is a security identity used by user-created apps, services, and automation tools to access specific Azure resources. You can create the appropriate principle by executing the following using the Azure CLI:

$ az ad sp create-for-rbac --name <your-sub-domain>  --password 

The console should display the following result with pertinent information:

{
  "appId": "cccccccc-cccc-cccc-cccc-ccccccccccccccc",
  "displayName": "cloud-tomee-azure",
  "name": "http://cloud-tomee-azure",
  "password": "",
  "tenant": "bbbbbbb-bbbbb-bbbb-bbbbb-bbbbbbbbbbb"
}

The <your-sub-domain> is called the service principal name in the Azure documentation. In this example http://cloud-tomee-azure. It has to be unique across Azure and you will need to choose your own.

The appId is the identification of the app service. You will need that next so copy and save it somewhere you can get to it.

Configure Maven

On the pom.xml we package the app with the tomee-maven-plugin, creating an executable jar. We need to use port 80.

To deploy on Azure we use the azure-webapp-maven-plugin with the following configuration:

<configuration>
   <authentication>
       <!-- Needs to match the server block on the settings.xml -->
       <serverId>azure-auth</serverId>
   </authentication>
   <deploymentType>jar</deploymentType>
   <jarFile>${project.build.directory}/${project.build.finalName}-exec.jar</jarFile>
   <stopAppDuringDeployment>true</stopAppDuringDeployment>
   <resourceGroup>tomee-group</resourceGroup>
   <appName>cloud-tomee-azure</appName>
   <region>ukwest</region>
   <pricingTier>B1</pricingTier>
   <linuxRuntime>jre8</linuxRuntime>
</configuration>

The region and pricingTier were chosen based on proximity and cost.

The appName must match <your-sub-domain>.

Next we need to edit Maven’s ~/.m2/settings.xml file so the azure-webapp-maven-plugin can authenticate on Azure:

<server>
  <id>azure-auth</id>
  <configuration>
 	<client>cccccccc-cccc-cccc-cccc-ccccccccccccccc</client>
 	<tenant>bbbbbbb-bbbbb-bbbb-bbbbb-bbbbbbbbbbb</tenant>
 	<key><password for this app></key>
 	<environment>AZURE</environment>
   </configuration>
</server>

Where the client is the appId and the tenant is the tennatId from the previous steps
You can now build the example and deploy it to Azure just using Maven:

mvn clean install -Pazure-single-jar azure-webapp:deploy

In the end this will return the base URL and path. In normal conditions, you could test your app by invoking:

http:///cloud-tomee-azure-8.0.0-SNAPSHOT/echo/send-this-back

It will return send-this-back.

Example:
https://cloud-tomee-azure.azurewebsites.net/cloud-tomee-azure-8.0.0-SNAPSHOT/echo/send-this-back

Workaround for the JAVA_HOME bug on Azure

Calling the URL should return the text “send-this-back”, but it may not because of this bug, currently being solved, affecting the value of the JAVA_HOME environment variable. While it’s not fixed, here’s the workaround:

Go to your Azure console, select your app service and go to Application Settings:

Then you need to manually set the JAVA_HOME value to /usr/lib/jvm/zulu-8-azure-jre-headless_8.33.0.1-8.0.192-linux_musl_x64 by adding a new setting here:

After the redeployment, you can refresh the app in the browser and see the result.

That’s it!
Your instance of TomEE is now running on the Microsoft Azure cloud service!

Now that you have the TomEE source code checked out you can also contribute to it! Take a look at “How to Get Started Contributing to TomEE or any Open Source Project”.