Deploying Applications with Gradle and XL Deploy

If you use Gradle to build your project, you can now automate project deployment using the new XL Deploy plugin for Gradle, which is available in the XebiaLabs community.

With this plugin you get a new task in your Gradle project, "deploy", which installs your application to a given environment. So you can easily deploy a new snapshot version of your project to development environment. Or you could hook the deployment task to your Gradle release process to automatically install a new version in an acceptance environment. In this post I will demonstrate how you can setup XL Deploy and Gradle to automatically install your applications. Note that if you have a CI server then you could as well use XebiaLabs CI plugins to execute deployment of successful builds, like Jenkins plugin, Bamboo plugin or TFS plugin.

How You Can Use It

---

The Gradle plugin uses XL Deploy to do the heavy lifting of application deployment. This means that you need to have a running instance of XL Deploy server, and it gives you a lot of benefits. You can configure any type of complex deployments, like deploying your application to a cluster of nodes behind a load balancer, for example. And once you've done that once, you can reuse it for development, acceptance and production environments, thus avoiding deployment-level bugs. Moreover you can deploy to both Windows and UNIX-based platforms, as well as a vast range of supported middleware, see this page for the list. There are three steps to getting Gradle and XL Deploy setup ready to deploy your applications:  

1. Install XL Deploy if you don't have it yet.
2. Configure the environment in XL Deploy where application will be deployed.
3. Add the xl-deploy plugin to your Gradle project.

I will show how to do that on example of a HelloDeployment web application which will be deployed to a Tomcat server. For simplicity, the Tomcat server will be running on localhost. If you never used XL Deploy before, please follow steps below to install it and configure an environment. Otherwise you can skip it.

Install XL Deploy

If you don't have XL Deploy yet you can install the free trial edition: just go to the download page and follow instructions. It should take around 5 minutes to install. When finished XL Deploy will be available at http://localhost:4516/ by default.

Configure An Environment

I need to let XL Deploy know where my Tomcat server is located. To do that I will configure a new "local" environment, in XL Deploy 4.5.2 it takes three steps:

1. Add your local machine to the Infrastructure tree of the Repository tab: [caption id="attachment_8652" align="alignnone" width="300"] Configure localhost[/caption]
2. Add a Tomcat server and its virtual host to the created infrastructure element. On my Mac it is installed at /usr/local/Cellar/tomcat/8.0.14/libexec. [caption id="attachment_8653" align="alignnone" width="300"] Configure Tomcat server[/caption] [caption id="attachment_8651" align="alignnone" width="300"] Configure virtual host[/caption] You can then test if configuration is OK by right-clicking on the created tomcat server and executing "stop" and "start" commands.
3. Create an Environment called "local" and add the Infrastructure/localhost/tomcat/localhost virtual host to it. This is where the web application will be deployed. [caption id="attachment_8650" align="alignnone" width="300"] Configure "local" environment[/caption]

If you have problems or your Tomcat setup is more complex than described here, you can check this tutorial. Note that by the time you read it the XL Deploy 5.0.0 may be out which has a fully revamped UI to configure environments.

Configure Your Gradle Build

Now when the XL Deploy setup is ready we get to the point when the xl-deploy Gradle plugin comes in play. I will be deploying a simple web application called HelloDeployment which is built using Gradle war plugin. After adding the xl-deploy plugin the build.gradle looks like following:

apply plugin: 'war'
apply plugin: 'com.xebialabs.xl-deploy'
version = "1.0-SNAPSHOT"
xldeploy {
  xldUrl = "http://localhost:4516/"
  xldUsername = "admin"
  xldPassword = "admin"
}
tasks.deploy.configure {
  environmentId = "Environments/local"
}
buildscript {
  repositories {
    jcenter()
    maven {
      url "http://www.knopflerfish.org/maven2/"
    }
    maven {
      url "https://dist.xebialabs.com/public/maven2/"
    }
  }
  dependencies {
    classpath 'com.xebialabs.gradle:xl-deploy-gradle-plugin:0.2.0'
  }
}

The xl-deploy plugin adds two tasks to the project: dar and deploy. dar task packages the application in a format understandable by XL Deploy. DAR package contains all artifacts which need to be deployed (there may be more than one in your application), and a special manifest file. The manifest file must be created by path src/main/dar/XL Deploy-manifest.xml in the project:

<?xml version="1.0" encoding="UTF-8"?>
<udm.DeploymentPackage version="${noSnapshot(project.version)}" application="HelloDeployment">
  <deployables>
    <jee.War name="HelloDeployment" file="${artifact(project.war)}" />
  </deployables>
</udm.DeploymentPackage>

The artifact(project.war) part of the manifest file adds the WAR file built by Gradle into the DAR package. You can read more about the "magic" functions you can use in manifest file in the README of the project. The deploy task uploads generated DAR file into XL Deploy and optionally executes the deployment. The environmentId parameter of the task shows to which environment to deploy. You can find more configuration options listed here. Finally you can execute the deployment using command gradle deploy. Use -i option to see more details about deployment tasks being executed:

➜ HelloDeployment git:(master) gradle deploy -i
...
:war
...
:dar
...
:deploy
Importing dar file /Users/bulat/fun/gradle-xld-plugin/src/test/resources/HelloDeployment/build/libs/HelloDeployment-1.0-SNAPSHOT.dar
Application [Applications/HelloDeployment/1.0-20150203-115939] has been imported
 ... Application not found in deployed => preparing for initial deployment
Deployeds to be included into generatedDeployment:
Creating a task
    -> task id: 2b7e0579-5eca-4884-ba33-27b444553235
Executing generatedDeployment task
-----------------------
Task execution plan:
-----------------------
2b7e0579-5eca-4884-ba33-27b444553235 Description    Initial deployment of Environments/local/HelloDeployment
2b7e0579-5eca-4884-ba33-27b444553235 State          PENDING 0/1
2b7e0579-5eca-4884-ba33-27b444553235 step #1 PENDING  Update the repository with your deployment.
-----------------------
Task execution progress:
-----------------------
2b7e0579-5eca-4884-ba33-27b444553235 step #1 DONE Update the repository with your deployment.
Updating the repository... OK
-----------------------
Task execution result:
-----------------------
2b7e0579-5eca-4884-ba33-27b444553235 Description    Initial deployment of Environments/local/HelloDeployment
2b7e0579-5eca-4884-ba33-27b444553235 State          EXECUTED 1/1
2b7e0579-5eca-4884-ba33-27b444553235 Start      2015/02/03 11:59:42
2b7e0579-5eca-4884-ba33-27b444553235 Completion 2015/02/03 11:59:42
2b7e0579-5eca-4884-ba33-27b444553235 step #1 DONE Update the repository with your deployment.
Updating the repository... OK
BUILD SUCCESSFUL
Total time: 6.918 secs

Now when you go to http://localhost:8080/HelloDeployment/ you should see the happy "Your application is deployed!" message. If you have any questions or problems - please do not hesitate to comment on this post or create an issue in the GitHub project! Happy deploying!