Authors
Bradley Beddoes

Applicable versions
Beta 2

We support JVM 1.4 releases. For tared files mentioned below the JVM 1.4 compliant binaries have -jvm1.4 appended to the file name.

Preparing your server

To successfully operate the Java SPEP your server must be accessible on port 443 from the ESOE system. You can ask your ESOE system administrator for the IP addresses ESOE will connect from if your running a restrictive firewall policy and update it appropriately. In some circumstances your administrator may allow you to configure port 80 unsecured SPEP instances. This is a per installation decision which your ESOE system administrator can advise you of.

The distribution of SPEP comes with 3 gziped tared files:

1. Extract spep-endorsed.tar.gz to your $TOMCAT/common/endorsed directory
2. Extract spep.tar.gz and copy the spep.war file to $TOMCAT/webapps
3. Create a core directory to store spep artifacts, a sub directory called config to store configuration and a sub directory called logging for log files. This must be readable by the user tomcat runs as. e.g /opt/spep/config and /opt/spep/logging
4. Copy the spep.config file to the configuration directory e.g /opt/spep/config/spep.config
5. At this point you have a choice in how to advise the SPEP install of your configuration location
   1. Java Property (RECOMMENDED). Export a java property called spep.data to your Java environment when tomcat starts. This should be set to the top level artifacts directory. e.g -Dspep.data=/opt/spep
   2. Create a Java properties file called spepvars.config and place it in $tomcat/webapps/spep/WEB-INF/ this is a standard java properties file format, set the variable spep.data to the same value you would above. We don't recommend this method though it may be useful in a multi spep environment, be sure to save your spepvars.config file safely, it will need to be copied back to the web application on each upgrade you perform, it may also be wise to recreate the shipped spep.war file with this file stored inside before starting tomcat.

The distribution of SPEP also comes with another gziped tared file called spepfilter.tar.gz this contains several jar files which you must locate in each web applications WEB-INF/lib directory that your deploying.

SPEP Registration

Navigate to the "Register Service" page of the ESOE Manager.

Enter values for the following fields:

Click Next.

Add Service Contacts

Select the contact type from the list, and enter the other details for the contact.
When this is filled in, click "Save contact".

You may edit and delete contacts after they have been saved. After you have finished entering contacts, click Next.

Add Service Nodes

The "SPEPNode URL" is used as the base URL for the SPEP endpoints. The different service locations here are paths to the service endpoints, using the SPEPNode URL as a base.

Select the server technology you are using. The default values for the endpoint paths will work for a default SPEP deployment.

Click Save Node. You may add more nodes and edit or delete nodes that have already been added.

After you have finished entering nodes, click Next.

Finalize registration process

From this page you may check the information you have entered, and also navigate back to previous pages to make any alterations by clicking the Previous button.

Once you are happy with the configuration, click Complete.

Service configuration

Navigate to your service in the ESOE Manager application. Click on the "get service configuration" link. In the service description, click on the "service node configuration" link.

This page shows you the configuration values that need to be set up in the spep.config file, which can be found at the location you've earlier configured for spep.data.

For each of the configuration options shown by the ESOE Manager service node configuration page, enter the corresponding value for the current node in its spep.config file.

It is very important that each node's configuration be correct. There may be some differences between them.

Save the keystore file by clicking the "download keystore" link. The keystore will be the same for all nodes. Store the keystore as spep.data/config/spepKeystore.ks

Protecting your webapp

There are 2 steps to configuring a web application to be protected by the SPEP:

1. Edit the tomcat/webapps/yourapp/WEB-INF/web.xml file so that it uses the filter.
2. Configure your webapp for cross context access.

The following should be placed in the web.xml file for your webapp to protect it with the filter:

<filter>
	<filter-name>spep-filter</filter-name>
	<filter-class>com.qut.middleware.spep.filter.SPEPFilter</filter-class>
	
	<init-param>
		<param-name>spep-context</param-name>
		<param-value>/spep</param-value>
	</init-param>
</filter>

<filter-mapping>
	<filter-name>spep-filter</filter-name>
	<url-pattern>/*</url-pattern>
</filter-mapping>

The param-value for the spep-context parameter should be changed to the location of the SPEP webapp in your Tomcat instance. By default this is /spep. The url-pattern in the filter-mapping section describes which part of the webapp to protect. By matching /* we protect the entire webapp.

Important note about cross context access
The SPEP webapp by default operates in the /spep context, or in whichever context it is placed. In order to have different paths such as /secure which are protected by an SPEP filter, cross context access needs to be enabled. This is enabled by default, by the context.xml file in the META-INF/context.xml.

Your application MUST also be enabled for cross context. To enable cross context access, the following should be placed in tomcat/webapps/yourapp/META-INF/context.xml:

<?xml version="1.0" encoding="UTF-8"?>
<Context path="/secure" crossContext="true">
  <WatchedResource>WEB-INF/web.xml</WatchedResource>
  <WatchedResource>META-INF/context.xml</WatchedResource>
</Context>

Logging

SPEP ships with support for Log4j logging. Each spep.war ships with a log4j configuration pointing at spep.data/logging for file output and by default logs at the INFO level. You may choose to modify this to suit your own needs but for general production usage INFO is considered sufficient.

Run the environment

Your environment is now able to be started, we reccomend you watch logging closely for the first little while to make sure all configuration is in order at which time you can lower the output of SPEP logging from DEBUG to INFO. To invoke spep simply point your browser at http://<<server [:port]>/_your_app/

Feedback

We aim to continually improve this documentation set to make it as easy as possible for new users and seasoned users alike to setup an SPEP. We welcome any comments or additions you may have on the ESOE users mailing list at any time.