Note: As of January 2012, the Quickstart has been replaced by an easier installation method
Installing the quickstart - Windows
Before you start on the quickstart, you'll need to have a java standard edition development kit (Java SE JDK) installed. A JRE alone is not enough as the quickstart runs inside Tomcat, which requires a JDK. At this stage I'd recommend a Sun/Oracle JDK rather than another flavour (such as IDM or OpenJDK). The reason for this is that all the Grouper binary releases are built using the Sun/Oracle JDK. The quickstart also requires that Apache Ant be installed.
Installing a JDK
For windows you need to download and install a recent version of the JDK (Java 6 is required for Grouper) from http://www.oracle.com/technetwork/java/javase/downloads/index.html - make sure you download the JDK. This is available in 64 bit and 32 bit versions (choose whichever suits your operating system, Grouper runs on both) for windows.
1. Once you've downloaded the JDK installer, you can install it by double clicking it to run the installer.
2. Choose the options you wish to install (the defaults will be fine).
3. Set where you want to install the JDK on your computer - again the default will be fine. Make a note of this location, as we'll refer to it from now on as JAVA_HOME.
4. Installation will complete, and you will now be equipped with a fully working Java development environment.
The easiest way to install Tomcat on Windows is to download the 32bit/64bit Windows Service Installer from the Binary Distributions, Core section at http://tomcat.apache.org/download-60.cgi. You will want the current stable version of Tomcat, which is 6.0.29 at the time of writing.
1. After downloading the file, install it by double clicking it.
2. Check through and accept the licence agreement - if you're worried about it it's a very permissive Apache Software license.
3. Choose the components you wish to install - the defaults will work fine.
4. Choose where to install Tomcat on your computer. Make a note of this location as we will be referring to it as TOMCAT_HOME from now on.
5. Set the port you want Tomcat to listen on - you can leave it as 8080 unless this port is already in use on your computer. You can optionally set the Tomcat Administrator Login details. These are not essential and we will not be using them.
6. Choose the location of the JDK that you previously installed (this will be JAVA_HOME). The installer will probably be able to guess this for you.
7. Compete installation, and optionally start Tomcat as a service and show the readme. Tomcat will now be installed as a Windows service and can be controlled in the same way as any other service.
Installing Apache Ant
Ant is a little more tricky to install as it does not come with an installer. You need to download the .zip file from http://ant.apache.org/bindownload.cgi
1. Decompress the file using the Windows extraction tools (right click → extract )
2. Choose where to extract Ant to. For consistency with other software that we've installed I've chosen to install it to C:Program|/C:/Program\ Filesapache-ant-<version>-bin. Make a note of this location which we'll refer to as ANT_HOME from now on.
3. Finish extracting the files and choose to Show extracted files.
4. Windows explorer will now open, navigate to the bin sub-directory and you will be able to copy the installation location into your clipboard to make it easy to add it to your system path.
5. Next you need to set your System Path to include the location of the Ant bin directory. To do this open Start → Control Panel → System
6. Click the environment variables button.
7. In the System variables pane, double click on the Path variable
8. Add the following onto the end of whatever is already there (take care not to completely overwrite ths existing content): ";<ANT_HOME>/bin". In our example this means that we are adding a semicolon ";" and pasting the location we have in the clipboard.
9. Next click the new button to add a new variable. Call it ANT_HOME and set it to the loction of the Ant installation (ANT_HOME). You can also paste from the clipboard and delete the trailing "bin". Click OK.
10. Now add another System variable, called JAVA_HOME with the location of the JDK installation (which we're referring to and JAVA_HOME). In our example this is c:program|/c:/program\ filesJavajdk<version>. Click OK.
11. Your environment is now set up, so you can close the System applet and test everything is OK by opening up a command prompt and typing ant<enter>. You should see an Ant error message as below. If you don't recheck the previous steps.
Setting up the quick start
You will need a program capable of extracting .tar.gz files to set up the quick start. There are many available - I use 7-zip from http://www.7-zip.com.
- Open windows explorer and navigate to the directory into which you downloaded the grouper-quickstart-1.6.1.tar.gz file
- Extract the contents of the file
You will now have a new directory in the same directory as where you were when you extracted the file. It will be called grouper.quickstart-1.6.1
The first task is to build the web application and install it into Tomcat
1. Open a command prompt, cd into the directory grouper.quickstart-1.6.1 and run the following command ant ui
2. You will then be presented with a list of options, type default and press enter,. The UI application will now be built
3. Before installing it into Tomcat, you need to copy a file to your Tomcat installation (or merge it if you have made other changes to the file for other reasons). You need to copy the tomcat-user.xml file from grouper.quickstart-1.6.1/grouper-ui to TOMCAT_HOME/conf where it will overwrite another file
4. Install it into Tomcat by copying the grouper.quickstart-1.6.1/grouper-ui/build/grouper folder into TOMCAT_HOME/webapps
Starting the quick start
1. Restart the Apache Tomcat service (optional, but may help if you have any problems)
2. Start the HSQL database that comes with Grouper. To do this open a command prompt, cd into the directory grouper.quickstart-1.6.1 and run the following command ant db
3. Now open a browser and go to http://localhost:8080/grouper you will see the login screen and can log in using the username GrouperSystem and the password 123 (these are contained in the
tomcat-users.xml file). You should now have a working copy of Grouper.