Deploying WAR files using wardeploy

This page talks about the wardeploy deployment mechanism for deploying WAR files to Azure Web Apps running Tomcat.

Why wardeploy

There are multiple ways to deploy a WAR (Web Application Arhcive) file to an Azure Web App running Tomcat, but the most common one is to use FTP to upload the WAR file in the /home/site/wwwroot/webapps directory. When Tomcat detects the presence of a new WAR file, it unpacks it and loads the web application from the directory the WAR file was unpacked to.

This works great when you have an Azure Web App that isn't scaled out. However, when you scale out the web app, multiple Tomcat instances race to unpack the WAR file leading to race conditions that may land one or more workers / instances in a bad state. This issue manifests in different ways, most common being a 404 status code when an incoming request is routed to any of the bad workers.

wardeploy is a deployment mechanism for addressing this problem.

How to use wardeploy

wardeploy is available as a REST API - /api/wardeploy - and can be used to deploy to an Azure Web App running Tomcat on either Windows or Linux. The following sections explain how to use it from bash and Powershell.

bash

Run the following script after editing the placeholder values for web app name, credentials, etc. This wiki page explains how you can get the credentials for your web app.

# *** BEGIN *** Customizations
sitename='site1' # if you site is site1.azurewebsites.net
username='yourusername' # Example: username='$site1' (NOT 'site1\$site1', NOT 'site1\site1'. Also, note the single quotes.)
password='yourpassword'
warFilePath='./test1.war'
# *** END *** Customizations

curl -X POST -u $username:$password https://$sitename.scm.azurewebsites.net/api/wardeploy --data-binary @$warFilePath

Powershell

Run the following script after editing the placeholder values for web app name, credentials, etc. This wiki page explains how you can get the credentials for your web app.

# *** BEGIN *** Customizations
$sitename='site1' # if you site is site1.azurewebsites.net
$username='yourusername' # Example: $username='$site1' (NOT 'site1\$site1', NOT 'site1\site1'. Also, note the single quotes.)
$password='yourpassword'
$warFilePath='D:\test1.war'
# *** END *** Customizations

$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $username, $password)))
$apiUrl = "https://$sitename.scm.azurewebsites.net/api/wardeploy"
Invoke-RestMethod -Uri $apiUrl -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)} -Method POST -InFile $warFilePath -ContentType "multipart/form-data"

Deploying to apps other than ROOT

By default, wardeploy deploys to the ROOT app. Optionally, you can simply use the query parameter name to specify the name of the app you want to deploy to: /api/wardeploy?name=NAME_OF_APP. For example, /api/wardeploy?name=myapp will deploy to the /home/site/wwwroot/webapps/myapp directory instead of /home/site/wwwroot/webapps/ROOT.

How does wardeploy work

wardeploy builds on top of zip push deploy. In simplest terms, it takes over the unpacking of the WAR file from Tomcat by unpacking it by itself. The WAR file is unpacked to a temporary location and the unpacked contents are then copied over to the appropriate directory in /home/site/wwwroot/webapps. While doing this, only the files that have changed since the previous deployment are copied. This works great with scaled out web apps as Tomcat no more performs the unpacking, thereby eliminating the race conditions.