<gbean name="DownloadedPluginRepos">
<attribute name="repositoryList">http://people.apache.org/~ammulder/plugin-repository-list-1.1.txt</attribute>
<attribute name="userRepositories">[http://people.apache.org/repo/m2-incubating-repository/org/apache/servicemix/geronimo/]</attribute>
<attribute name="downloadRepositories">[http://www.geronimoplugins.com/repository/geronimo-1.1/]</attribute>
</gbean>

Steps for Installing ServiceMix on Geronimo 1.1

OVERVIEW

The benefits of ServiceMix and Geronimo have been well covered elsewhere - especially within the official ServiceMix site, so this article focusses exclusively on the mechanics of getting a deployment of ServiceMix 3.0 running within the Geronimo 1.1 container.

In a follow up article, I hope to cover an enterprise deployment pattern for the combination Geronimo/ServiceMix which shows how the two can be deployed/tweaked to provide the same level of functionality and resilience that many corporate environments will have achieved using commercial application servers and ESB/EAI servers, e.g. clustered point to point, hub and spoke etc.

BACKGROUND

The installation of Geronimo and ServiceMix themselves, and subsequent releases of components running within these containers are heavily based on Maven.  Although there are other alternatives such as Ant, or combinations of command line tools, if you are going to be getting serious with Geronimo/ServiceMix then you should know your way around Maven.  A good place to get started with Maven is to read the Getting Started page from start to finish.  (As a long time Ant user I found a by-product of using ServiceMix was that I learnt enough about Maven to convince me that I should leave Ant behind)

This article assumes nothing about any existing tools on your system, and makes use of the newest versions of the required tools.  This isn't to say that it won't work with earlier version e.g. Maven, but it does mean that you're probably going to have to roll up your sleaves and start debugging the build/deployment process.

Note: This articule was written very shortly after the release of 3.0 of ServiceMix.  Many of the steps below will mostly likely be redundant once the documentation/tooling catches up with the functional changes in 3.0.

STEPS

Note: You are free to work with your own preferred directory structure, but the steps below will refer to the directory structure I always use.  I have included fixed local directory names so that the steps below should be exactly reproducible.  The steps also assume that you have a JDK installed (I used JDK 1.5.0_06 for the following steps)

1. Download and Install Maven

The version I used is version 2.0.4.  I downloaded the binary distribution of Maven to get things started.    I use a Windows PC for development, so in my case this meant downloading the maven-2.0.4-bin.zip file, and unpacking this into my c:\apps\tools{color} directory to c:\apps\tools\apache\maven-2.0.4.  In subsequent steps I will refer to this directory as <maven home>.

A key concept in Maven is the repository that Maven uses when working with a project.  A base install of Maven starts with the core of Maven in the distribution, but the first time you actually use it "in anger" it will recursively examine all of the libraries that Maven/your application is dependent on, and it will download all of these files into a structured repository.  By default a new installation of Maven will use ~/.m2 as your repository - isolating the repository you use from others.  This is not the place to go into best practice for locating a Maven repository, but for the sake of this guide, I changed the location of the repository to point to a different location.

To do this, navigate to your <maven home>\conf directory, and open the file settings.xml.  Edit this file using a text editor - you will need to look for the tag <localRepository> which will be in a commented out section.  Uncomment this line, and edit it to point to somewhere you are comfortable with.  In my development environment, this is set up to point to a shared software repository on a network share, so my repository is set to <localRepository>s:/working/repository/<localRepository>.  In subsequent stpes I will refer to this as <maven repository home>

2. Download and Install Geronimo

The version I use is the Tomcat build of version 1.1.1.  I download the binary distribution of Geronimo.  I unpacked this into my standard directory structure to create c:\apps\tools\apache\geronimo-tomcat-j2ee-1.1

3. Get ServiceMix Source

The full suite of plugins/code required to integrate ServiceMix 3.0 with Geronimo 1.1 is not available within binary distribution of ServiceMix, so you will need to download the source files.  To get this, you will need a client for the source control tool Subversion on your machine.

3.1 Download and Install Subversion Client

There are a number of different subversion clients, for a number of different operating systems - as a Windows user I use TortiseSVN from Tigris, but you can use any client for the remaining steps.  If you want to want to go with TortiseSVN (highly recommended) then you can download it from here.  The Windows version is an installer that hooks into the Windows shell - so I installed with the default options.

3.2 Check out the source

It's best to create a clean directory to check out the source code.  This is because Subversion (like CVS) will create a directory (e.g. .svn) to hold meta information, and if you attempt to check out code from multiple locations (maybe not now - but ServiceMix might be the first of many) you could run into problems with meta data from one project overwriting another.  In my case I created the directory c:\working\external\servicemix.  In subsequent steps I will refer to this directory as <servicemix src home>.

Assuming you have TortiseSVN installed, right-click in the new directory (c:\working\external\servicemix) and select "SVN Checkout...".  When the dialog box appears, in the "URL of repository:" field enter "https://svn.apache.org/repos/asf/incubator/servicemix/tags/servicemix-3.0", and then press OK.  The Checkout dialog will appear and you *should* start to see a listing of the files/directories that are being checked out to your machine.

4. Change the Geronimo Plugin Repository Configuration

The build also uses a Geronimo Maven plugin to install the final product into Geronimo.  Maven essentially treats plugins like dependencies, and will download the plugins that are required.  This is configured through a file, and the version of the configuration that is included in the 3.0 source has a reference to a candidate-release repository version.  This needs to be changed to get Maven to use the correct version of the plugin.

Navigate to the <servicemix src home>\geronimo\servicemix\src\resources\META-INF directory, and open the file geronimo-plugin.xml in a text editor.  Search for the line

<source-repository>http://incubator.apache.org/servicemix/dist/servicemix-3.0-M2-incubating/m2/</source-repository>

and replace it with

<source-repository>http://people.apache.org/repo/m2-incubating-repository/</source-repository>

5 Build ServiceMix and the Geronimo Plugin

The next commands will use Maven to build the ServiceMix source code that you've just download and place it into the local Maven repository.  This will recursively download all dependencies required- which comes to something like 128Mb of disk space.  If you are worried about disk space/time then you can read more about Maven repositories to learn how to configure Maven to point to an existing repository that you may already have, or a shared repository that someone in your team may have placed on the network.

Note: A lot of Windows step-by-step guides will tell you to set PATH, JAVA_HOME etc. in the system environment variables.  This is bad practice as it enforces a system wide value - and doesn't allow you to configure on a case by case basis (e.g. different VM's for different versions of a product).  Everthing should either be entered directly in a command window (time consuming) or wrapped in a script e.g. (setupJava5.bat, setupMaven2.bat etc.)... but thats another article.

• Open a DOS prompt (Start -> Run - "cmd")
• Navigate to the source code directory:

cd <servicemix src home>

• Set the PATH to include the Maven scripts:

SET PATH=%PATH%;<maven home>
e.g.
SET PATH=%PATH%;c:\apps\tools\apache\maven-2.0.4

• Set the JAVA_HOME to point to your JDK install:

SET JAVA_HOME=<jdk home>
e.g.
SET JAVA_HOME=c:\apps\tools\jdk1.5.0

• Run the first pass of compilation - This is required to build some of the pre-requisites required to compile the second pass:

mvn -Dmaven.test.skip=true -Dprofile=step1 install

• Run the second pass of compilation:

mvn -Dmaven.test.skip=true -Dprofile=step2 install

• Run the second pass of compilation a second time - I copied this step from a forum posting and it seemed to be required - I'm sure it will disappear in point releases:

mvn -Dmaven.test.skip=true -Dprofile=step2 install

6 Install the Geronimo System Plugin

Amongst other things, the previous steps created an archive that can be deployed to Geronimo.  The last step will deploy this into a running Geronomi server.

• Start Geroninmo - Open a DOS prompt (Start -> Run - "cmd") and run the following command

<geronimo home>\bin\geronimo.bat

• Open a DOS prompt (Start -> Run - "cmd")
• Set the JAVA_HOME to point to your JDK install:

SET JAVA_HOME=<jdk home>
e.g.
SET JAVA_HOME=c:\apps\tools\jdk1.5.0

• Run the Geronimo deployment tool:

java -jar <geronimo home>bin/deployer.jar install-plugin <maven repository home>\org\apache\servicemix\geronimo\servicemix\3.0-incubating\servicemix-3.0-incubating.car

• The last step should report success both in the window in which you ran the deployment command, and in the window that Geronimo is running in.

I will post samples of what the compile steps look like, and what the successful install looks like shortly, but I've already delayed publishing this for too long so I wanted to get this up.  Hopefully you are now on your way to actually working with the ServiceMix product.