Wednesday, May 11, 2011

Displaying Build Numbers in Grails Apps

Being a fan of Continuous Delivery, identifiable builds, and Continuous Integration: I like to deploy web apps with a visible build number, or some other way of identifying the version. For example, having the build number on the login screen for example. In the Maven/Java world, this is straightforward. Or at least I know the idioms. I struggled with this a bit while working on a Grails app,  and wanted to share my solution. There may be other, better, solutions, but the ones I found approaches that didn't quite work they way that I'd hoped.

My requirements were:
  • To display a build number from my CI tool, where the number was passed in on the command line. In Bamboo, for example you might configure a grails build as
    -Dbuild.number=${bamboo.buildNumber} war
  • To only change build artifacts and not any source files.
  • To not misuse the app version, or change the names of any artifacts.
  • To be simple and idiomatic.
I realized that that Grails itself changes the application metadata (application.properties) when it does a build. So I modeled this approach after code in one the gant scripts in the Grails distribution.
The steps are:
  • Hook into a build event to add a property in to application.properties.
  • Access the property using the gsp tag.
  • Pass the value into the the grails war command using a Java property.
To create the event hook, create a file in your project/scripts directory called _Events.groovy that contains a method like:

eventCreateWarStart = { warName, stagingDir ->
    def buildNumber = System.getProperty("build.number", "CUSTOM")
    println("Setting BUILD_NUMBER to "\+ buildNumber)
    ant.propertyfile(
       file:"${stagingDir}/WEB-INF/classes/application.properties") {
         entry(key:"build.number", value:buildNumber)
   }
}

Then you can access the property with a GSP tag like this

<g:meta name="build.number">


And you can now display build numbers (or any other properties that you want to pass in from you CI system) in your Grails app. This worked for me with Grails 1.3.7. The only down sides are:

  •  This works on a per-project basis (That is probably easily fixable)
  • The properties that we set are hard coded. (this could be fixed with a convention  that iterates through all of the system properties that start with "build" for example).
I welcome any suggestions for improving this, or alerts that I'm using the entirely wrong idiom :)

8 comments:

bugle said...

Very helpful post, as having access to that build number can really help track down issues with a deployment. I also like the idea of non-hard-coding the property names by doing a search for build*.

One additional thought, I've run into problems changing application.properties in a CI environment before because on a subsequent build Subversion wouldn't update the file due to a conflict. Make sure builds are SVN reverting all the locally changed files or ignoring conflicts.

Steve Berczuk said...

Note that in this approach the application.properties isn't changed. Only the version that is derived from the compile step, so you don't need to worry about version management system issues.

leanjavaengineering said...

An alternative approach is to use the grails set-version script as part of your CI build
e.g. Grails & Hudson Part 4: Automated Deployment.

This will change the application.properties but only in the CI workspace.

Steve Berczuk said...

Thanks for posting the link to the chapter on Grails and Hudson Deployment. I considered using set-version, but (without any other changes) it changed the artifact name, and also overloaded what "version" meant. But if you did set version and then named the war on the command line, you could get a similar result. ie"grails prod war ${project.name}-${project.version}.war" you could get the same result. (or if you were willing to not have the version in the war name).

leanjavaengineering said...

I'm not keen on having the version number in the war filename as it often complicates the deployment.
E.g. if you're automating the deployment with Cargo then it will undeploy say ggug.war and deploy the new ggug.war (any upstream Apache proxying to allow external client access remains unchanged etc.).

Steve Berczuk said...

True, the version number in the artifact name can complicate things. A way around that is to use context files and unzipped wars (with Tomcat anyway).

The set-version +build specifying the war name in the grails war command could work well.

I also wanted to fit into an otherwise maven-ized environment where versions in artifact names are common. So what I wrote seems simpler given my requirements.

The one thing that I don't like with the approach I wrote is that it requires a change to each project. Though with some conventions, one could simply change the grails environment on the build server to add the build number property.

At least now anyone reading this will see a couple of options.

Anonymous said...

Very nice. Thanks for posting.

Anonymous said...

Found this approach elegant and helpful. In our case, we used placed a new _Events.groovy file in the user directory on the CI server (rather than in the project directory.) This way we could alter a non-tracked file and use it only on the machine whose build numbers we cared about for QA purposes. Thanks for the helpful post.