...

Installing Apache HTTP server to sit in front of Tomcat.

It is common (and good practice) to install Apache HTTP server to site between the client browser and the Tomcat application server.

• Client browsers connect to a webserver on port 80 by default (for non-secure connections) and 443 (for default connections). Connecting to an alternative port requires that port to be included in the address in the form http://<server>:<port>/<location>. Typically users prefer not to bother with the port
• Ports below 1024 are typically reserved for privileged users (such as root). Tomcat could listen on Port 80 instead of 8080, but would need to run as root in order to do so. This would mean that all code running inside Tomcat would also be running as root - not a good idea from a security point of view!
• Apache HTTPD server is engineered to initialise as a privileged user, then run all processes as a non-privileged user. It is therefore an ideal candidate for acting as an intermediary between the client browser and tomcat
• Typically, port 80 is allowed through firewalls (perhaps via a proxy server), but port 8080 is not
• It is a good idea to access the Grouper UI through an encrypted connection. Setting Apache up to service an SSL connection is easier than doing so for Tomcat

Obtaining and installing Apache HTTPD server is beyond the scope of this document, and procedures depend on your operating system and distribution. Apache HTTPD 2.2 with the mod_proxy and mod_proxy_ajp modules is recommended, so please consult your system documentation to go about getting it. Once it's up and running, the following configuration snippet will proxy incoming connections to the tomcat ajp connector running on port 8009:

ProxyPass /grouper ajp://localhost:8009/grouper/
ProxyPassReverse /grouper ajp://localhost:8009/grouper/

For documentation on these apache modules see http://httpd.apache.org/docs/2.2/mod/mod_proxy.html^{Image Added} and http://httpd.apache.org/docs/2.2/mod/mod_proxy_ajp.html^{Image Added}

It is also possible to proxy to a range of backend servers, balancing connections between members of a cluster. We will use this as one option for setting up a basic cluster for the Grouper UI in a later section. See http://httpd.apache.org/docs/2.2/mod/mod_proxy_balancer.html^{Image Added} for more details.

If you are running on a Microsoft server platform then Internet Information Server can perform the same task in a slightly different way. One way of doing this can be found at http://www.iisadmin.co.uk/?p=8^{Image Added}

Installing Grouper UI on the application server

The Grouper UI now needs to be built with your grouper configuration files. Download the Grouper UI from http://www.internet2.edu/grouper/software.html^{Image Added} at the time of writing the most up-to-date version is found at http://www.internet2.edu/grouper/release/1.6.2/grouper.ui-1.6.2.tar.gz^{Image Added}

Unpack the downloaded archive, we will refer to the location on the file system where it is unpacked as GROUPER_UI_SRC from now on. You will also need both Java and Apache ant set up. Please refer to the quick start section for details of how to do this.

Rename the GROUPER_UI_SRC/build.properties.template file to GROUPER_UI_SRC/build.properties and edit it. Change the value of the grouper.folder property so that it points to your GROUPER_HOME directory (the location of the grouper.apiBinary-<VERSION> in which you edited the configuration files and ran gsh during setup). This ensures that the build process has access to the grouper libraries and your configuration files. This will mean that it will connect to the same grouper database and subject source(s) as the grouper Daemon, which is required.
If you wish, copy the file GROUPER_UI_SRC/log4j.properties.template to GROUPER_UI_SRC/log4j.properties and edit it to change the log levels and locations
Open a command line, and from within GROUPER_UI_SRC run this command:

ant war

This will build an installable web application archive called grouper.war which you will find in GROUPER_UI_SRC/build. Copy this file to TOMCAT_HOME/webapps. You will also want to edit the password for GrouperSystem contained in GROUPER_UI_SRC/tomcat-users.xml and copy the file to TOMCAT_HOME/conf. Restart tomcat. If you have setup Apache HTTPD in from of Tomcat, point your browser to:

http://<tomcat host>/grouper/

If you are running tomcat without Apache HTTPD point your browser to:

http://<tomcat host>:8080/grouper/

You should show be able to log in as GrouperSystem using the password you set in tomcat-users.xml.