Overview

The hydrant project was developed to automate deployment of applications whose code and dependencies are stored in a CVS repository.

For each application that hydrant automates, these files are typically created:

hydrant.properties

A set of properties defining the CVS-managed file sets to be checked out of the repository in order to build and deploy the application, along with other deployment-specific properties.

build.xml

A set of Ant targets that perform CVS checkouts; call targets in checked-out build.xml files; and copy files to deployment target.

A set of Unix shell scripts in the root-directory of the hydrant project are employed to run the automated builds. Invocation of the builds from the top-level shell script is described below. The scripts are designed for multiple application builds based on a set of shared third-party dependencies and shared local codebase; they may be run for a single application as well.

A typical hydrant deployment involves this sequence of (scripted) steps:

• set appropriate environment variables (within deployment-script scope)
• checkout ist-jxde project (third-party dependencies and shared artifacts)
• checkout a core distribution of JBoss (application server)
• checkout the Streek project (shared classes and other resources)
• build Streek code in the appropriate deployment mode (e.g., qa or prod)
• checkout the servant project, and use it to generate deployment-specific JBoss server(s)
• build application(s); for each application built atop the dependencies described above:
  • check out application-specific dependencies
  • check out and build application code
  • deploy (copy) the built application, or notify user of manual tasks necessary to complete deployment
  • run test suite(s)

A "check out" in the list above implies checking out a set of files from a CVS repository, as specified by properties (including CVS tags) found in a hydrant.properties file.

Preparing an application for Ant-scripted deployment

An application is ready for Ant-scripted deployment to a QA or Production environment after:

• it is developed and tested in a development-environment;
• application-specific components and dependencies, such as application-specific JBoss server(s) generated using the servant project (documented here), are developed and tested in a development-environment;
• the codebase (source code), related scripts, and third-party dependencies (e.g., appropriate version of JBoss) are committed to CVS; and,
• each fileset that will be checked out in the course of the hydrant deployment is appropriately tagged in its repository.

Creating a hydrant deployment for an application

The Ant script (build.xml) for hydrant is typically simple and straightforward. Examination of existing hydrant sub-project files, preferably those created for a project that uses components similar to the new one, is the most efficient way to understand what the new set of hydrant files will look like. An example is included in this document.

• Map out the sequence of steps (CVS checkouts & Ant target executions) that must occur to deploy the application in question. It may be helpful to refer to the typical deployment listing above.
• Create a new directory under the hydrant/ project root, and name it with a reference to the application to be deployed. The hydrant files you create will be located in this directory.
• Create a build.xml for the deployment that will execute the necessary sequence of steps. Modeling the new build.xml on an extant one may prove the most efficient route to writing the Ant build file, if care is taken to avoid thoughtless copy-&-paste errors.
• Create a hydrant.properties file for the application, referring to extant file(s) for reference as necessary and helpful. It should contain:
  • deployment-specific properties (such as jboss.server, the name of the server to which the app will be deployed)
  • CVS-related properties (such as the CVS root and tag) for each discreet fileset to be checked out
  • any additional properties needed for Ant scripts to be run by the hydrant build script (such as the name of a target in the application's build.xml file to be invoked in lieu of the default)
  • properties needed to build a webapp-pinger, if appropriate (cf. example)
• Test the newly-created hydrant fileset, commit it to the CVS repository, and tag it appropriately when all is copacetic.

The following example of a hydrant.properties file may be helpful:

# hydrant properties for BearFacts
#

# 
# deployment mode one of test, qa, prod
#
deploy.mode=qa

#
# automated local deployment if local.deploy is set to any value
#
#local.deploy=xxx

#
# cvs access
#
cvs.access=:ext:${env.USER}@canvas.berkeley.edu
#
# development environment
#
#
# jboss
#

jboss.home=${env.JBOSS_HOME}
jboss.server=streek-bearfacts
jboss.deploy.dir=${jboss.home}/server/${jboss.server}/deploy
jboss.version.project.name=jboss-3.2.5

#
# Bearfacts
#
# autodeployment occurs if bearfacts.autodeploy is set to any value
bearfacts.autodeploy=XXX
bearfacts.home=${env.CVSHOME}/bearfacts
bearfacts.cvs.root=${cvs.access}:/usr/local/cvsrep/org/sis
bearfacts.tag=v1-0-0-ism-rc1c
#bearfacts.target=ebill-ear-${deploy.mode}
bearfacts.target=ear-${deploy.mode}


#############################################
# webapp-pinger properties
#############################################
#
# Base Properties
#
context.root.base=bearfacts

test.base.server.protocol=https
test.base.host.name=sis.berkeley.edu
test.base.http.port=80
test.base.https.port=443

#
# smoke.test.template.file is set when the application
#  requires a different smoke-test template from the
#  default
#
smoke.test.template.file=smoke-test-template-bearfacts.jmx

#
# URLs
#
# it is expected that this URL will cause app to return login page:
#  ${test.base.server.protocol}://${test.base.host.name}/${test.base.context.root}/${protected.resource.url}
#
# it is expected that this URL will submit login form:
#  ${test.base.server.protocol}://${test.base.host.name}/${test.base.context.root}/${submit.login.form.url}
#
# it is expected that this URL will submit login form:
#  ${test.base.server.protocol}://${test.base.host.name}/${test.base.context.root}/${submit.logout.request.url}
#
protected.welcome.page.url=student/studentMain.do
submit.login.form.url=student/j_security_check
submit.logout.request.url=login/logout.jsp

#
# JMeter Response Assertions
#

# web.server.not.found.assertion:  
#     appears in web server 404 (not found) error (e.g., Apache)
# web.server.not.available.assertion:
#     appears in web server service not running error
#     (e.g., Apache cannot find JBoss server or 
#     app running in JBoss server)
# app.server.not.found.assertion
#     appears in app server 404 (not found) error (e.g., JBoss)
web.server.not.found.assertion=404 Not Found
web.server.not.available.assertion=503 Service Temporarily Unavailable
app.server.not.found.assertion=HTTP Status 404

# at.login.page.assertion:
#     appears in login page
# login.success.assertion:
#     appears in welcome page (after successful login)
# logout.success.assertion:
#     appears in logout page (after successful logout)
at.login.page.assertion=CalNet</a> ID to access <b>Bear Facts</b>
login.success.assertion=Welcome to Bear Facts for Students</title>
logout.success.assertion=Logout</title>

#
# User ID and pwd
#
test.login.id=test-212383
test.login.password=!!PasswordNotIncludedInThisDocumentation!!
test.bad.password=xxxNotAPasswdxxx
      

Running a hydrant deployment

Prepare an empty directory in which to run the hydrant deployment. A significant quantity of data will be written to this directory; make sure sufficient space is available!

Follow these steps to run the deployment:

• Check out the hydrant files prepared above into an empty directory. Note that you will need to check out hydrant sub-projects that are dependencies of the application(s) you wish to build (these are likely to include: the ist-jxde, jboss, streek, servant and webapp-pinger sub-projects).
• Edit the checked-out copy of the shell script hydrant-env.sh to conform to the environment (e.g., filesystem) in which the hydrant build will be run:
  • set the value of CVSHOME to the filesystem location where this shell script is located
  • if testing the script on Windows/Cygwin, set the value of CVSHOME_PREFIX as described in the shell-script comments; otherwise the value should be null
  • set the value of CVS_RSH to the SSH implementation on the machine where this script will be run, as described in shell-script comments (e.g., ssh for most UN*X machines)
• run the top-level shell script, hydrant, with appropriate command line arguments (note that some example command-line invocations are checked into CVS; your invocation may be modeled after these):
  • command line parameters that begin with -D will be passed to each sub-project build.xml script; e.g., -Ddeploy.mode=test
  • command line parameters that begin with -X are command line arguments passed to Ant; e.g., -Xms512m -Xmx512m
  • each additional argument (separated by a space) is a hydrant sub-project that will be built, in the order listed in the command-line invocation - note that each sub-project must be listed after all of its dependencies; a typical example might be: ist-jxde jboss streek servant app1 app2 app3...
  • the following is an example of a command-line invocation of the shell script:
    hydrant -Ddeploy.mode=test -Xms512m -Xmx512m ist-jxde jboss streek servant app1 app2 app3
• respond to prompts appropriately

Running hydrant deployments on a Windows box

To run hydrant deployments on a Windows box, install Cygwin, a Linux-like environment that runs on the Windows OS. You will need to install Cygwin's CVS package in addition to the basic Cygwin environment. Install other Cygwin utilities and packages as needed/desired.

The shell script hydrant-env.sh must be modified to appropriately handle Cygwin's references to the Windows filesystem. The comments in this shell script describe Cygwin-specific settings. The version of this file committed to CVS should not be one for which Cygwin-specific variable values have been set, because the actual (as opposed to test-only) usage of hydrant deployments is typically on UN*X filesystems.

Testing the scripted deployment

Test as you normally would for the type of deployment performed. For example, if your deployment is to a JBoss application server, start the server and confirm that your application is being appropriately served by it.

Scripted testing is strongly recommended, and may be invoked as part of the same hydrant build script with which the application is deployed (see typical deployment sequence, above).