Grouper QuickStart

This Grouper installation contains:

Installation

The basic installation steps are

  1. Prepare tomcat.
  2. Arrange logging.
  3. Build and deploy the UI.
  4. Start the included database.
  5. Log in to the UI.

Details for each are in the following sections. This installation process assumes that al components will run on the same machine. Other configurations are possible.

Prepare Tomcat

This document assumes you are familiar with Tomcat.

The Grouper UI requires that users authenticate themselves and this QuickStart relies upon Tomcat's default authentication mechanism which is based on <TOMCAT_HOME>/conf/tomcat-users.xml. Open grouper-qs/grouper-ui/tomcat-users.xml and copy the lines inside the <tomcat-users> tags to the tomcat-users.xml file for your Tomcat installation. This file contains login details for all the QuickStart subjects

Restart Tomcat.

Arrange Logging

As of v1.3.0 the UI has improved error handling and logging. To take advantage of new logging fetaures review and uncomment the lines:

#use.local.log4j=true
#local.log4j.output-dir=c:/tomcat_5-5/logs/

and set an appropriate directory. You may choose to have errors delivered by email - choose an appropriate error.append value and configure:

error.mail.to
error.mail.from
error.mail.host

Log File Location and Permissions

By default, the quickstart package expects log files to exist in the grouper/logs/ subfolder where the package is built. These files must be made writable by the tomcat user.

An alternative location can be specified either by replacing the system property ${grouper.home} in the grouper/conf/log4j.properties file prior to building the UI, or by starting tomcat with a parameter setting that system property to another value, e.g., by adding "-Dgrouper.home=<grouper dir>" to the tomcat startup command.

Build the UI

Review grouper-qs/grouper-ui/build.properties. If you want the build script to automatically install the UI in your Tomcat instance uncomment and set the appropriate value for deploy.home. If you do not set this you will need to copy the UI to your Tomcat installations webapps directory.

Change directory to grouper-qs and type ant ui.

A list of build targets* is displayed. If you have set deploy.home press default. Otherwise type dist or war. If the former, copy grouper-qs/dist/grouper to <TOMCAT_HOME>/webapps, or, if the latter, copy grouper-qs/dist/grouper.war to <TOMCAT_HOME>/webapps.

You may want to review grouper-qs/grouper/conf/log4j.properties and, if necessary, modify the values for the keys:

to valid / appropriate paths on your system. Use / as a directory separator whichever operating system you are using.

*If you want to take advantage of the 'nice' targets you must uncomment and set appropriate values for all the deploy properties in grouper-qs/grouper-ui/build.properties. In addition you must make grouper-qs/grouper-ui/catalina-ant.jar available to ant. If you call a 'nice' target and catalina-ant.jar is not available, you will be prompted to input whether you want the script to copy catalina-ant.jar to a directory, .ant/lib, under your home directory (or see the Ant documentation for other options). You will have to run Ant again for it to find the newly copied jar file.

Starting HSQLDB

HSQLDB is configured to run on the default port of 9001. If you already have a database running on that port you must choose a different port and update the JDBC urls in grouper-qs/grouper/conf/grouper.hibernate.properties and grouper-qs/grouper/conf/sources.xml. Whenever you change any files in grouper-qs/grouper/conf you should rebuild the UI and restart the grouper web application.

An Ant target is provided to start the database as a server. Change directory to grouper-qs and type ant db.

HSQLDB is packaged with a database manager application which lets you run queries against database tables. To run the manager applciation change directory to grouper-qs and type ant dbgui.

Logging in to the UI

Using a web browser access the UI e.g. http://localhost:8080/grouper/. Login as GrouperSystem - using the password from the tomcat-users.xml file.

The Demo Database

The HSQLDB database comes preloaded with Subject data (see grouper-qs/subjects.xml) and a set of stems and groups (with members) and access and naming privileges set (see grouper-qs/quickstart.xml).

The UI respects Grouper's privilege model and so what you see depends to some extent on who you are. You may compare the views seen by different users based on the privileges derived from grouper-qs/quickstart.xml.

Customising the UI

Uncomment the line:
#additional.build=${basedir}/../custom-grouper-ui/additional-build.xml

in grouper-qs/grouper-ui/build.properties and rebuild the UI as described above. Restart the webapp, and access it in your browser.

There are various changes to the layout, branding and on screen text, as well as a different login mechanism - one which doesn't require a password!

All the files needed for the customisations are in grouper-qs/custom-grouper-ui, which can be used as a template for how to make your own customisations. Information on how to customise the Grouper UI is available.

Using the QuickStart instance with a different database

You should only try using a different database after you have successfully setup the default QuickStart.

If you want to run the QuickStart against your own data* you may:

  1. start with an empty HSQLDB database, or
  2. an empty supported database from another vendor

*running ant schemaexport and ant db-init (see instructions below) creates the database tables and essential data for Grouper to work. The Grouper UI allows you to create new stems and groups, but not subjects. See Loading your own data for details on how to batch load data.

Setting up the QuickStart with an empty HSQLDB database

  1. Shutdown the demo HSQLDB database if it is running
  2. backup grouper-qs/grouper/dist/run/grouper.script
  3. restart the HSQLDB database
  4. from grouper-qs/grouper type ant db-init
  5. restart the grouper web application

Settng up the QuickStart with an alternative supported database

  1. stop the HSQLDB database if it is running
  2. modify grouper-qs/grouper/conf/grouper.hibernate.properties by commenting out the default hibernate.dialect, hibernate.connection.driver_class and hibernate.connection.url keys under #HSQLDB.
  3. modify grouper-qs/grouper/conf/grouper.hibernate.properties by uncommenting the same keys under their chosen database, ensuring a valid conection url and correct hibernate.connection.username and hibernate.connection.password values. Check and comply with any database specific instructions in grouper.hibernate.properties
  4. Copy any required Jar files for your JDBC drivers to grouper-qs/grouper/lib/custom
  5. from grouper-qs/grouper type ant db-init
  6. modify grouper-qs/grouper/conf/sources.xml to specify an appropriate subject source. You may implement your own source or specify appropriate JDBC connection parameters (see JDBCSourceAdapter documentation). Step 5 automatically creates subject and subjectattribute tables required by the JDBCSourceAdapter, so you may use the same database connection url, username and password as you specified in grouper.hibernate.properties
  7. from grouper-qs type ant ui
  8. restart the grouper web application

Loading your own data

You may load Subject data, into the tables specified by the JDBCSourceAdapter, directly using a tool which executes SQL statements. grouper-qs/subjects.sql shows a SQL script which was used to create the subjects in the demo database. Additional attributes may be added. Ensure that you commit any subjects you add before using them.

For Grouper 0.6 it was necessary to include a subject GrouperSystem. This is no longer a requirement, and, in fact, defining GrouperSystem will cause errors.

When loading subjects who you want to be able to login to the Grouper UI, you must specify a loginid attribute.

You may use the XML import / export tool to load stems, groups, memberships, privileges and custom group types

Further Reading

Release documentation for the Grouper API.

Grouper UI specific documentation.