Binary deployment of your Sakai tool: Part II

This is the second in a series (of two) covering the binary deployment of tools in Sakai. In Part 1 we covered polishing the Maven POMs. In this article we’ll go through the use of the Maven Assembly pluginto generate a binary Tomcat overlay bundle which can be pushed to a Maven repository. Then we can easily fetch and deploy the tool automatically without the need for checking out and building from source.

I’ll be using examples from Profile2, and later, we will deploy Profile2 to Sakai, as a Tomcat overlay.

Step 1. Create an ‘assembly’ directory in your project source:
Step 2. Create an assembly descriptor in your assembly directory. For consistency sake, call it deploy.xml and put it in src/main/assembly:
This assembly descriptor describes all dependencies that need to be included, and how they should be laid out in the bundle that is created. It also tells the Assembly plugin to create a zip file of this layout. When we deploy, the zip will be unpacked and the artifacts inside will simply overlay on top of Tomcat.
tomcat-overlay
zip
false
shared/lib
false
org.sakaiproject.profile2:profile2-api:jar:*
components/profile2-pack
false
org.sakaiproject.profile2:profile2-pack:war:*
true
webapps/
${artifact.artifactId}.war
false
org.sakaiproject.profile2:profile2-tool:war:*
false
${project.basedir}/README*
Step 3. Create a pom.xml in your assembly directory so we can expose all dependencies to the Assembly plugin, execute the Assembly descriptor, create the Tomcat overlay and deploy it to our local repo:
4.0.0
Profile2 Assembly
org.sakaiproject.profile2
profile2-assembly
pom
org.sakaiproject.profile2
profile2
1.3-SNAPSHOT
org.sakaiproject.profile2
profile2-api
${project.version}
compile
org.sakaiproject.profile2
profile2-impl
${project.version}
compile
org.sakaiproject.profile2
profile2-pack
${project.version}
compile
war
org.sakaiproject.profile2
profile2-tool
${project.version}
compile
war
org.sakaiproject.profile2
profile2-util
${project.version}
compile
org.apache.maven.plugins
maven-assembly-plugin
2.2-beta-2
org.apache.maven.plugins
maven-install-plugin
2.2
maven-assembly-plugin
src/main/assembly/deploy.xml
make-assembly
package
attached
You’ll note that all internal dependencies are included. Also note that in the ‘build’ section we have told the Assembly plugin where to find the descriptor. If you change the location of the file, you’ll need to change this value as well.
Step 4. Build
Issue a ‘mvn clean install‘ and if all went well, you’ll have a new zip artifact in your local repository, which contains everything your project needs for a successful deploy. I’ve unpacked the Profile2 tomcat-overlay zip so you can see the structure:
That’s it. If you have access to a Maven repository, push all of your project’s artifacts to the repository and start promoting the binary deployment of your Sakai tool. Profile2’s trunk artifacts have been deployed to the Sakai Maven snapshots repo, and we’ll try it out below.
How to use the binary artifact:
In order to actually use the Tomcat overlay we created in the steps above, we need to tell Maven to use it. If you have a recent check out of the Sakai trunk source, you’ll see a new directory called ‘core-deploy’. This is simply a POM that lists a number of Tomcat overlay’s to deploy to Sakai. The very observant will also notice that there is no ‘search’ module anymore (in addition to several other components that used to be in the Sakai source). This is because Search has been completely converted into a Tomcat overlay and the source is no longer required to build Sakai. The artifacts are fetched from the remote repository when when the deploy goal is run by Maven.
Take a look at the core-deploy/pom.xml. Build profile’s aside, this tells Maven to clean up certain directories in Tomcat, then to deploy our Tomcat overlay zips. They’ll also be unpacked according to the Assembly descriptor (see Step 2).
Here is a cut down block you can use to deploy trunk Profile2 (and TinyUrlService) to Sakai using only it’s binary artifacts:
profile2
components/profile2-pack;
components/tinyurl-pack
tomcat-overlay
org.sakaiproject.profile2
profile2-assembly
1.3-SNAPSHOT
tomcat-overlay
zip
org.sakaiproject.tinyurl
tinyurl-assembly
0.9-SNAPSHOT
tomcat-overlay
zip
Add this to a POM, then execute it via mvn clean install sakai:deploy -P profile2 and the Profile2 Tomcat overlay will be fetched from the remote repository, installed into your local repository and unpacked into Tomcat. No need for source!