This Grouper installation contains:
The basic installation steps are
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.
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.
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
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.
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.
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.
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 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.
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.
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:
*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.
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