Example

Assume you want a toolset containing Apache Directory Server, Tomcat, and LDAPBrowser. Tomcat should be configured to use the directory server for authentication, and the directory should be configured with an administration user for accessing the Tomcat management console.

Prerequisites

  • You must already have Java 1.5 installed

Install

  • Unzip the ToolInstaller download into a directory - from now on this directory will be referred to as <TOOLINSTALLER_HOME>.

ToolSet Definition

The ToolSet contains 3 tools - Apache Directory Server, Tomcat, and LDAPBrowser. You can find this toolset in <TOOLINSTALLER_HOME>\docs\samples\tools-repo\toolsets\appserver-sample.xml.

Modifications are required for:

  • Directory Server configuration
    • configure the dc=sample suffix
    • populate the directory with the user uid=admin,ou=people,dc=sample
  • Tomcat
    • configure Tomcat to use the directory server at localhost:389 for authentication
  • LDAPBrowser
    • configured with a connection to the directory server

You can find the modification archive in <TOOLINSTALLER_HOME>/docs/samples/tools-repo/tools/modifications/appserver-sample-1.0.zip.

<toolset>
        <name>appserver-sample</name>
        <modification>
                <id>
                        <groupId>modifications</groupId>
                        <artifactId>appserver-sample</artifactId>
                        <version>1.0</version>
                        <!-- type forced to being zip at this point in time -->
                </id>
        </modification>
        <tools>
                <tool>
                        <name>Tomcat</name>
                        <id>
                                <groupId>org.apache.jakarta.tomcat</groupId>
                                <version>5.5.9</version>
                                <artifactId>jakarta-tomcat</artifactId>
                                <url>http://archive.apache.org/dist/jakarta/tomcat-5/v5.5.9/bin/jakarta-tomcat-5.5.9.zip</url>
                                <type>zip</type>
                        </id>
                        <wrappers>
                                <wrapper>
                                        <target>bin/startup.bat</target>
                                        <alias>tomcat-start</alias>
                                        <shortcut>Tomcat Start</shortcut>
                                        <changedir>true</changedir>     
                                </wrapper>
                                <wrapper>
                                        <target>bin/shutdown.bat</target>
                                        <alias>tomcat-stop</alias>
                                        <shortcut>Tomcat Stop</shortcut>
                                        <changedir>true</changedir>     
                                </wrapper>
                        </wrappers>
                        <shortcuts>
                                <shortcut url="http://localhost:8180/manager/html" name="Tomcat Manager"/>
                                <shortcut url="http://localhost:8180/tomcat-docs" name="Tomcat Docs"/>
                                <shortcut url="http://jakarta.apache.org/tomcat/" name="Tomcat Home"/>
                        </shortcuts>
                </tool>

                <tool>
                        <name>ApacheDS</name>
                        <id>
                                <groupId>org.apache.directory.apacheds</groupId>
                                <version>0.9</version>
                                <artifactId>apacheds</artifactId>
                                <url>http://archive.apache.org/dist/directory/binaries/apacheds-0.9/apacheds-0.9.zip</url>
                                <type>zip</type>
                        </id>
                        <wrappers>
                                <wrapper>
                                        <target>java -jar apacheds-main-0.9.jar config.properties</target>
                                        <alias>ApacheDS-Start</alias>
                                        <shortcut>ApacheDS Start</shortcut>
                                        <changedir>true</changedir>     
                                </wrapper>
                        </wrappers>
                        <shortcuts>
                                <shortcut exe="${tool.basedir}/docs/index.html" name="ApacheDS Docs"/>
                                <shortcut url="http://directory.apache.org/subprojects/apacheds/index.html" name="ApacheDS Home"/>
                        </shortcuts>
                </tool>

                <tool>
                        <name>LDAPBrowser</name>
                        <id>
                                <groupId>gov.anl.mcs</groupId>
                                <version>2.8.2-b2</version>
                                <artifactId>ldapbrowser</artifactId>
                                <url>http://www-unix.mcs.anl.gov/~gawor/ldap/dwld/bin-dwld.cgi?fileid=282b2zip</url>
                                <type>zip</type>
                        </id>
                        <wrappers>
                                <wrapper>
                                        <target>start javaw -classpath lib\ldap.jar;lib\jndi.jar;lib\providerutil.jar;lib\ldapbp.jar -jar lbe.jar</target>
                                        <alias>LDAPBrowser</alias>
                                        <shortcut>LDAPBrowser</shortcut>
                                        <changedir>true</changedir>     
                                </wrapper>
                        </wrappers>
                </tool>

        </tools>
</toolset>

Install the appserver-sample toolset

Note that this will require downloading almost 20MB as the tools do not exist in the sample repository and they will have to be retrieved from their sources on the internet. If you already have the archives and don't want to download them again, you can manually add them to your repository in the format illustrated below.

Run the installer providing 3 required parameters and 1 optional:

  • -d the directory to install the toolset
  • -r the repository url
  • -t the name of the toolset to install
  • -i to allow internet downloads (optional)

From TOOLINSTALLER_HOME, run the command

 installToolSet.bat -i -d d:\temp\tools -r file:///\<TOOLINSTALLER_HOME\>/site/samples/tools-repo -t appserver-sample

The archives will downloaded and saved into your local-repository. This is in your user home directory i.e. C:/Documents and Settings/<YOUR_USER_NAME>/.toolsinstaller/local-repo.

You should see output like the following as the tools get installed:

Installer Initialised
 Tools home : d:\temp\tools


 Installing toolset : appserver-sample
  Installing tool   : Tomcat
   Created wrapper  : tomcat-start.bat
   Created exe shortcut : Tomcat Start
   Created wrapper  : tomcat-stop.bat
   Created exe shortcut : Tomcat Stop
   Created url shortcut : http://localhost:8180/manager/html
   Created url shortcut : http://localhost:8180/tomcat-docs
   Created url shortcut : http://jakarta.apache.org/tomcat/
  Installing tool   : ApacheDS
   Created wrapper  : ApacheDS-Start.bat
   Created exe shortcut : ApacheDS Start
   Created exe shortcut : ApacheDS Docs
   Created url shortcut : http://directory.apache.org/subprojects/apacheds/index.html
  Installing tool   : LDAPBrowser
   Created wrapper  : LDAPBrowser.bat
   Created exe shortcut : LDAPBrowser
   Created setup script  : setup-env-appserver-sample.bat
  Applied modifications : appserver-sample-1.0.zip
Done.

If a tool already exists (if the directory exists) installation of that tool will be skipped - however, the modifications will still be installed, overwriting existing files.

To force reinstallation, just manually delete a selected tool or the entire toolset.

Installer Initialised
 Tools home : d:\temp\tools


 Installing toolset : appserver-sample
  Installing tool   : Tomcat
  Tool exists - skipping installation [Tomcat]
  Installing tool   : ApacheDS
  Tool exists - skipping installation [ApacheDS]
  Installing tool   : LDAPBrowser
  Tool exists - skipping installation [LDAPBrowser]
   Created setup script  : setup-env-appserver-sample.bat
  Applied modifications : appserver-sample-1.0.zip
Done.

For each toolset, a setup environment file will be created. In this example, D:/temp/tools/appserver-sample/setup-env-appserver-sample.bat is created and looks like:

@echo off
SET TOOLS_HOME=D:\temp\tools
SET APPSERVER-SAMPLE_HOME=%TOOLS_HOME%\appserver-sample

SET TOMCAT_HOME=%APPSERVER-SAMPLE_HOME%\jakarta-tomcat-5.5.9
SET APACHEDS_HOME=%APPSERVER-SAMPLE_HOME%\apacheds-0.9
SET LDAPBROWSER_HOME=%APPSERVER-SAMPLE_HOME%\ldapbrowser

Multiple wrappers can be created for each tool. These wrappers are essentially scripts which can be used to launch programs contained in the tool - but first they call the setup-env scripts so that the environment is configured correctly.

The tomcat-start.bat wrapper specified above is created as d:/temp/tools/appserver-sample/tomcat-start.bat:

call .\setup-env-appserver-sample.bat
cd jakarta-tomcat-5.5.9

bin\startup.bat %*

Shortcuts can also be created to point to the generated wrappers or other resources with the tool. Here, a shortcut to the tomcat-start.bat wrapper is created. Shortcuts are created in [tools_home]/shortcuts/[toolsetname]. It can be useful to add the [tools_home]/shortcuts directory as a tool bar to your windows Start bar. You can do this by right clicking on an empty part of the start bar, go to toolbars, and select New Toolbar..., and select the shortcuts directory.

For command line applications such as ANT or Maven, you may want to add the toolset directories to your path.

Run the tools

Go to the d:/temp/tools/shortcuts/appserver-sample directory.

Double click on the ApacheDS Start shortcut to start Apache Directory Server. You should see the Directory Server console open:

D:\temp\tools\appserver-sample>call .\setup-env-appserver-sample.bat
server: loading properties from config.properties
server: started in 1322 milliseconds

Now run the LDAPBrowser shortcut. This will open the LDAPBrowser window. Connect to the localhost server and navigate the directory.

Connect to the localhost LDAP directory

Notice the admin user in the manager group.

The directory is pre-populated

Now start tomcat by running the Tomcat Start shortcut. This will launch Tomcat but the ports have been changed - it will be listening on [http://localhost:8180/].

Run the Tomcat Manager shortcut to launch the management console. You will be prompted for a username and password. Use the username admin with the password password. This is how the admin entry in the LDAP directory is configured.

The local repository

All of the artifacts downloaded for this install are stored in the local repository. Browse to C:/Documents and Settings/<YOUR_USER_NAME>/.toolsinstaller/local-repo and have a look.

The directory structure should look like this:

tools/
        gov/anl/mcs/ldapbrowser-2.8.2-b2.zip
        org/apache/directory/apacheds/apacheds-0.9.zip
        org/apache/jakarta/tomcat/jakarta-tomcat-5.5.9.zip
        modifications/appserver-sample-1.0.zip
toolsets/
        appserver-sample.xml

You can copy this directory to a webserver and use that as your remote repository. Add the archives required by your team, and define the toolsets you find appropriate.