Deploying a Java application to Windows Azure with Command-line Ant

Date: Wednesday, December 14, 2011, 12:00:00 AM

Tags:

Table of Contents

Recommended Reading

Whether you are building a brand new application, or already have something built and wish to take advantage of the high availability and scalability of the Windows Azure cloud, this tutorial will show you how to package and deploy your application and runtime elements.

Download the Windows Azure Starter Kit for Java

To start things out we need to go download the Windows Azure Starter Kit for Java from the CodePlex project page.

The files can be found at: http://wastarterkit4java.codeplex.com/

The Windows Azure Starter Kit for Java uses Apache Ant as part of the build process. If you are not familiar with Ant, go check the installation manual which can be found at http://ant.apache.org/manual/index.html. Ant can be downloaded from the Apache project page at http://ant.apache.org

Note: Ant requires several environment variables to be set, ANT_HOME, CLASSPATH, and JAVA_HOME. Ensure these are set correctly. See http://ant.apache.org/manual/install.html#setup


Inside the Windows Azure Starter Kit for Java

The file you just downloaded is a Zip file that contains a template project. You need to first extract the project. This is a pretty straight forward process. Right click on the archive, choose "Extract All…" and select the destination to extract the project to.

If you look inside this archive you will find the typical files that constitute a Java project, as well as several files we built that will help you test, package and deploy your application to Windows Azure.

image

The main elements of the template are:

File nameDescription
.cspack.jarContains the Java implementation of the windowsazurepackage Ant task extension
ServiceConfiguration.cscfgThis is the Azure service configuration file. See the "What next?" section for more details
ServiceDefinition.csdefThis is the Azure service definition file. See the "What next?" section for more details
package.xmlThis is the Ant build script for your project
HelloWorld.warThis WAR file is provided as a very simple sample upload. Since we want to build a snazzy web application we can safely delete this file
startup.cmdThis script is run each time your deployment is started. Here you will define anything that needs to take place on startup, such as installing and starting a Java server, or firing off a background service
samples directoryContains a number of sample startup script for assorted Java servers that you can just copy and paste into your startup.cmd script, and follow the instructions inside them
run.cmdThis script is run after your deployment starts. It is not supposed to exit for as long as your deployment is healthy. If it exits, Azure considers that a request for a role instance recycle. Inside this sample run.cmd, you will see a call to util/whileproc.cmd with java.exe as a parameter. This is a simple script that keeps checking every 15 seconds if the java.exe process is running
unzip.vbsa utility script to make it easy to unzip zipped archives from your startup steps
download.vbsa utility script for downloading files from URL locations into the approot as part of the startup. This helps avoid the need to embed certain types of files, for example large and rarely changing files (such as the Java runtime, or a server distribution) into the deployment package itself, making it smaller and faster to upload. The URL could point to any download that does not require additional authentication (such as public websites, or Windows Azure blobs with anonymous access enabled) or one where all the authentication information needed is embedded in the URL (such as Windows Azure blobs with shared access signature authentication enabled.)
SampleRemoteAccessPrivate.pfxA sample private key containing a certificate you can upload to the Windows Azure Portal to enable Remote Desktop connectivity to the VM running your role instance. See the Remote Desktop tutorial for how to use it
SampleRemoteAccessPublic.cerThe public key-only version of the certificate for the sample remote access configuration that works "out of the box" in the Starter Kit. This is needed for encrypting your remove desktop password. See the Remote Desktop tutorial to learn more about this

Pick a server startup script sample

The project template is designed to work with multiple Java server environments.

As we progress through this tutorial I will show you how to setup the following servers, all of which are covered by the sample startup scripts in the project directory: Tomcat, Jetty, JBoss and GlassFish. These are among the most common, but you are not limited to using just these servers though.

After you decide which server to use, go to the samples folder and pick the corresponding startup script. Open it and copy all of its contents, then open your startup.cmd and replaced all of its contents with the copied contents. The close the sample script, so that you don't accidentally make changes to it. From this point on, all your changes should go inside startup.cmd.

You will notice that the sample you copied already contains simple instructions for what to do next. Regardless of which server you are using, the steps follow the same general pattern. Step 1 is to just copy the sample into your startup.cmd - you just did that, so on to the remaining steps…

Add a JDK.zip distribution to your approot

As with the server, feel free to choose whatever JDK you prefer. For this sample, I will be using JDK v1.6 from Oracle. Remember, that since Windows Azure is a 64 bit system, you need the 64 bit version of the JDK and whatever Java server you're using. That means that to install that 64-bit JDK and test your deployment in the Windows Azure emulator, you need to be using a 64-bit Windows OS.

First install the JDK on your own PC. ; Then zip the JDK directory of your installation in such a way that the ZIP file name is JDK.zip, and inside it it has just one folder called JDK, which has all the contents of the JDK inside (among them the JRE folder).

(For more information on this general issue, you cen see this stackoverflow article http://stackoverflow.com/questions/1619662/where-can-i-get-the-latest-jre-jdk-as-a-zip-file-i-mean-no-exe-installer)

Then copy the JDK.zip into your approot folder.

image

Add a server distribution to your approot

As per the instructions in the sample startup script, the next step is to add a distribution of the server to the approot. To minimize the number of changes you need to make in the startup script, it's best to stick to the file names assumed by the script by default. So depending on the server you're using, rename the ZIP that you download from the web as follows:

ServerZIP file name
Apache Tomcat 7.xtomcat7.zip
GlassFish Server OSE 3.xglassfish3.zip
JBoss Application Server 6.xjboss6.zip
JBoss Application Server 7.xjboss7.zip
Jetty 7.xjetty7.zip

Then copy that ZIP file into your approot folder (for example, tomcat7.zip):

image

Next, it is important to update the SERVER_DIR_NAME environment variable in your startup script with the directory name where your server will be unzipped. Just look inside the ZIP file and copy the exact name of the folder. This is important, because typically server releases have a very version-dependent directory names. The sample is pre-configured with one specific version for each server, but by the time you read this tutorial, it will likely not be the latest one that you'll be downloading. So you'll need to update this variable accordingly, otherwise your deployment will fail.

Note: DO NOT use quotes nor any leading nor trailing whitespace around your server directory name in an environment variable setting

If you have gotten this far, your server deployment is ready to go. Actually, even if you do not include your own application at this point, you could just build this now, and run in in the Windows Azure Emulator. You'd see your server running, with the sample HelloWorld app deployed to it. The HelloWorld.war application package comes with the Starter Kit, you see it showing up in the approot and referenced by the WAR_NAME variable in your startup script. if you want to give this a try already, then jump to the "Build and test in the emulator" section below.

Prepare your Java application

At this point, you can delete the sample HelloWorld.war file from the Windows Azure project.

It is important to note that the Windows Azure Project is merely a deployment project, it is NOT a Java coding project per se. It is not intended to contain any Java code in it. In real world scenarios, you would have your Java applications in separate projects. So I'm going to assume you already have created some sort of a Java project, and you are able to export a WAR file from it which contains your application. Then follow these steps to include your application in your Windows Azure package:

  1. Call your application file MyWebApp.war. (or whatever name you choose)
  2. Copy the that WAR file into the approot (you can automate this with a build step if you want to)
  3. In startup.cmd, modify the WAR_NAME setting accordingly, setting it to MyWebApp.war, or whatever name you chose. For example:
WAR_NAME=MyWebApp.war

Note: DO NOT use quotes nor any leading nor trailing whitespace around your WAR file name in an environment variable setting

At this point, your approot contents should look like this:

image

Your Windows Azure project is now ready to be built and deployed to the emulator.

Build and test in the emulator

Open a Windows command prompt, navigate to your project directory and run this Ant command line:

ant -buildfile package.xml

The command tells Ant to use the information contained within the package.xml file to build your application. Be patient, this could take some time depending on the size of your application and the resources available on your machine. If the build was successful you should see output similar to:

image

Your project by default is configured for local deployment to the emulator (packagetype="local" in package.xml). A folder named "emulatorTools" is created next to the "deploy" folder after you build the project. The emulatorTools folder will contain two command scripts that make it much quicker and easier to deploy to and reset the Windows Azure compute emulator and run your service in it:

  • RunInEmulator.cmd
    • This script will start up the local Windows Azure development cloud and deploy your project to it. (If you are using development storage you will still need to start the Storage Emulator manually.)
  • ResetEmulator.cmd
    • Removes any running instances of your application from the Compute Emulator, unlocks the files in use by the emulator and shuts down the development fabric. You should run this when you're done testing.

So the final step is to descend into the emulatorTools directory and run the server in the emulator:

cd emulatorTools
RunInEmulator

Your application should now be running on port 8080. Open your web browser and type http://localhost:8080/MyWebApp into the URL bar.

Package for the Windows Azure cloud

Now I need to talk a little more about the package.xml file. If you open the package.xml file you will find a specific tag that controls whether your application is built for local development or production on the Windows Azure cloud. The tag you are looking for in package.xml is:

<windowsazurepackage 
    packagefilename="WindowsAzurePackage.cspkg" 
    packagedir = "${wapackagedir}" 
    packagetype="local" 
    projectdir="${basedir}" 
    definitionfilename="ServiceDefinition.csdef" 
    configurationfilename="ServiceConfiguration.cscfg" 
>

Take note of the packagetype attribute. This attribute can be set to either local or cloud. When packagetype="local" your application will be built into the exact structure that will be on the Windows Azure cloud, however it is not archived for upload, but instead it is prepared for use in the emulator. If packagetype="cloud" then your deployment will be built and archived as a .cspkg file. You can then log in to the Windows Azure Portal and upload the .cspkg and .cscfg files to deploy your application in the cloud.

The package.xml is a powerful Ant build file with many options for customizing your application. The file contains a wealth of comments that describe many of the options available to you.

Deploy to the Windows Azure cloud

Deploying your application to the Windows Azure cloud is as simple as logging in to the Windows Azure Portal and uploading a few files as follows:

If you have not done this before, first upload the PFX cerificate file to your hosted service's certificate store. This is needed to enable remote desktop to the virtual machine that will be running your deployment in the cloud. Its purpose is to help you with troubleshooting your deployment logic and learning about Windows Azure. (See the Remote Desktop tutorial for more).

Next create a new deployment and upload the .cspkg and .cscfg files generated when you build your package for the cloud.

For specific details on deploying please see the following articles:
http://msdn.microsoft.com/en-us/library/gg433027.aspx
http://msdn.microsoft.com/en-us/windowsazure/ff798117.aspx

Congratulations, you now have successfully setup and run your first Windows Azure application! Check out the links in the "What next?" section for more examples.

What next?

 
blog comments powered by Disqus