Customizing 'indie' releases

Owned by Former user (Deleted)
Last updated: Aug 18, 2010 by Former user (Deleted)Version comment
4 min read

Note: this document borrows heavily from an email that Anthony Whyte sent me in Jan 2010. Mistakes are my fault, not his, although this is a wiki right, so if you see some, be a champ and correct will you?

Tons of sakai projects are now on 'indie' release - why do you care?

The Good:

  • Projects don't have to follow Sakai's release schedule, they can release whenever they feel ready.
  • You can install newer tools in older Sakai - don't have to update all of Sakai to get the latest of a particular tool.
  • Sakai project is smaller, more manageable footprint
  • Add you own here

The Bad:

  • Indie projects aren't in your sakai source anymore....where did they go?
  • They get deployed to Sakai during maven build behind the scenes...not immediately obvious what version of indie projects you're getting
  • How do I make my own local mods?!?!?!

Here's what you need to know:

During the Sakai build, maven will download nice packages of these indie releases, stash them in your maven repository, and then deploy them all out to your tomcat.

You can tell what versions are hotwired into your OOTB Sakai check out by looking at sakai-src/master/pom.xml - you'll see all the versions for all the indie projects listed there.

Here's a list of some the indie projects right now (the main ones):

Kernel
Tests & Quizzes (SAMigo)
Messages & Forums (msgcntr)
BasicLTI
EntityBroker
Profile2
SiteStats
Common
edu-services

Here's a very basic primer on how to modify on of these projects to include your own local mods.

I imagine that you have an svn checkoout of sakai somewhere? Let's say this location is:

working/sakai-src

In this example, we'll say SAMigo is the tool we're modifying. So you'll want to checkout SAMigo at the same level as Sakai (not inside the Sakai dir as you may have done previously):

working/sakai-src
working/samigo

Obviously, you can structure it differently, but the takeaway is that the samigo dir should not be inside the sakai dir. It's not necessary any more as they are separate projects.

Start with a clean Tomcat and an empty .m2/repository/org/sakaiproject/samigo folder (e.g. delete it).

The idea here is that you want to load your customized version into your maven repo before sakai goes to stash a pre-packaged vanilla version in there.

The following takes you step-by-step. These instructions assume you're working with trunk. If you're working with a different version of SAMigo (like, say 2-7-x), just make sure that the version of SAMigo you checkout and the version Sakai thinks it's using agree. Otherwise, Sakai will keep using it's vanilla version and ignore your custom version and you won't see any changes!

1. Download samigo-trunk

cd samigo/trunk
mvn clean install

The above step puts samigo 2.8-SNAPSHOT into your local repo. You should see the .war file in /samigo-app. You should see an assembly .zip in samigo-assembly (among other samigo stuff).

2. Build sakai-trunk

mvn clean install -Dmaven.test.skip=true sakai:deploy

Maven will check your repo first for samigo 2.8-SNAPSHOT artifacts before it checks elsewhere. Note, however, that it will check the snapshot repo for the latest snapshot update and if it finds one it will download it and use it (keep this in mind). I don't expect this to be a problem in this case however. Maven, based on the core-deploy pom (in sakai trunk) will deploy the samigo-assembly zip tomcat overlay file to your $CATALINA_HOME during the deploy phase.

So the Sakai core-deploy pom handles the Samigo deployment. So in step 1 above you do not need to do mvn clean install sakai:deploy from samigo-trunk to get Samigo into Tomcat before building and deploying Sakai.

3. Start Tomcat

Once, you have Samigo deploying correctly locally, you might want to use the -o param to tell Maven not to look beyond your local repo (which implies that you need to make sure it is fully stocked with required artifacts first).

mvn -o clean install -Dmaven.test.skip=true sakai:deploy

4. Modifying Samigo

So assuming you have Samigo trunk deploying properly to Tomcat I'll assume you want to edit the code. Easy enough, edit it and perform a mvn clean install sakai:deploy to update your local samigo artifacts as well as deploy samigo to Tomcat. I don't think you will need to delete the existing samigo artifacts in Tomcat beforehand. Then stop and restart Tomcat.

That's it!

One thing you may want to consider is creating a special version of the tool for your institution/organization.

If you need to create your own version of Samigo trunk you will need to update the samigo pom versions to say "yourinstitution-2.8-SNAPSHOT". Then do a mvn clean install to put the artifacts in your local repo. Then update the master pom <samigo.version.property> appropriately:

in trunk master:
<sakai.samigo.version>2.8-SNAPSHOT</sakai.samigo.version>
to
<sakai.samigo.version>yourinstitution-2.8-SNAPSHOT</sakai.samigo.version>

before building and deploy Sakai trunk code to Tomcat.

You may want to consider setting up your own external maven repo to store your institutional artifacts (if one does not already exist).

5. Gotcha: signing the audio-jar (specific to SAMigo, not relevant for other indie releases)

If you don't already know, SAMigo's audio does need to be signed. As of 2.7.x, the audio jar can be signed as part of the build process. HOWEVER, if you are building SAMigo seperately, as these instructions have you do, then it won't get signed and you need to do it the old-fashioned way. Detailed instructions are here: http://confluence.sakaiproject.org/display/SAM/2.6+Release+Notes

These steps can be extrapolated to work with any indie release. Please don't hesitate to edit for clarity or ask questions.

Extra reading here:

http://blogs.uct.ac.za/blog/daves-blog/2009/11/22/managing-local-changes-to-maven-bundles-part-1