[Home] [About] [FAQ] [Software] [Documentation] [Contact]

System Administration - Installation & Deployment

Introduction

Before starting, please sign up for all applicable mailing lists. Announcements pertinent to Signet deployments, developments, and resources for deployment assistance can be found here. You may also contribute your Signet comments, questions, and concerns to these lists.

Your Contributions –
Signet is an open source community supported product. Your contributed experience is a valuable addition to the support of Signet. If you would like to contribute your own personal experiences with deploying Signet, please visit the Signet mailing lists.

Having trouble?
If you are looking for helpful hints, look in the appendix section below and our Troubleshooting tips for contributed tips from fellow users. You may also contact us.

Signet Installation Check-list

Below is a simplified component check-list that needs to be complete for your own successful installation of Signet. Please refer to the detailed installation instructions for more information.

Phase I: Preparation/Prerequisites

Java
Identity Management infrastructure
Authentication Mechanism
OS, compatible with Tomcat

Phase II: Signet Download (& QuickStart Installation)

Download the Signet Distribution of choice (& unpack .zip, .tar, etc.)
Signet v1.0 - proceed to Phase III , or
Signet-QuickStart

• Set your JAVA_HOME environment variable.
• Run the supplied start-up script.
• Load Signet in a browser

Phase III: Configure Tomcat

Create a "Signet" web application context in your servlet container.

Phase IV: Set up the Database

Execute the DDL.

Phase V: Configure Database Connection

Copy JDBC driver (2 destinations).
Configure [both] hibernate.cfg.xml files.

At this point, the Signet software itself is installed and ready. The remaining steps begin to give it content, shape it for your site, and connect it to your infrastructure:

Phase VI: Configure User Interface

Use your site-specific logo.
Customize the feedback URL.

Phase VII: Configure Subject Sources

Configure [both] sources.xml files.

Load the sample organization-tree data.
Load the sample Subsystem data.
Load the sample Subject data.

Phase IX: Load Signet

Tomcat (servlet container) available
Database available
Accessible via browser

Next Steps – back to Documentation:

Running & Supporting
Extending & Integrating

Note: If you decide to reconfigure any aspects of the Signet-Quickstart, it is recommended that you reload Signet in a browser after each change, to verify the success of any changes you have made.

Phase I — Prerequisites/Preparation

This section reviews general environment considerations for installing Signet. If you do not already have Java, the following steps can guide you before proceeding with the Signet distribution download (Phase II).

JAVA

Signet is built using Java 1.4.2. Your version of Java should be 1.4.2 or later.

If you are installing Signet into an environment that already has Java, e.g., an institutional server or a Java equipped personal machine like Mac OSX, you only need to know which version you have and can skip this step.

To verify if you have Java, or which version you have, use a browser and go to http://javatester.org/version.html.

If needed, download and install JDK 1.5.0_04+ (5.0) from http://java.sun.com/j2se/1.5.0/.

The Signet application is a JAVA based toolkit and UI, and requires a JDBC compatible RDBMS database for persisting data. There are additional requirements outside of Signet that are essential to a successful deployment of Signet:

• Sufficient institutional identity management infrastructure to provide user and subject information for the population covered by Signet privilege management, typically an enterprise directory service, a Person Registry or equivalent. For more information on how your institutional identity management infrastructure is important to a successful implementation of Signet, refer to the Manager's Guide.


• A method to authenticate browser users, preferably in the form of an enterprise authentication service. Some form of an SSO or a WebISO service is not explicitly necessary for Signet, but is highly recommended.


• A Java servlet container; Signet requires Servlet API 2.4 or higher. It has been tested on Windows, Linux, Mac OS X, and Solaris with Tomcat, but should work with any compatible servlet implementation. If you would like to share your experiences with the Signet community, please visit the Signet Wiki [coming soon] to contribute your comments and verification information.


• It is recommended that a web server such as Apache be deployed in front of Tomcat to provide authentication services and to control the flow of requests to Tomcat.
  

Tomcat

The supported and recommended servlet container is Apache Tomcat v5.x. This version has been included with the Signet-QuickStart distribution, and is nested within the demo directory. For configuration details, please look to Phase III – Tomcat Configuration.

Should you wish to use a different servlet container for production level use, it is expected that you will support it locally. Tomcat 4 with the proper JDK should work as well, but has not been tested yet, and is therefore not officially supported.

Phase II — Signet Download

The Signet v1.0 distribution is available in two forms:

• Signet v1.0 - a leaner version, intended for advanced installation (included are necessary utilities, libraries, and XML files), OR
• Signet-QuickStart - a bundled demo version, which includes Tomcat and HSQLDB preloaded with a demo population and assignments.

Download the current Signet distributions here, and unpack into a local directory of choice: e.g., /usr/local/signet/

Note: If you download Signet, proceed to Phase III. If you download the Signet-QuickStart, please see below.

Note: If you choose to use your own servlet container and/or database server on top of the Signet-Quickstart, it is advised that you repeat Steps 4-6 after each configuration change – in this way, you will ensure that you have completed each configuration step correctly.

To install and load Signet-QuickStart:

1. Download the Signet-QuickStart distribution.
   (Note: Use the .zip file for Windows and the .tar.gz file for unix/Mac; the former has Windows style linefeeds; the latter preserves execution permissions needed for unix scripts).


2. Unpack the distribution (.zip for Windows, or .tar for Mac/Unix) in the local directory of choice: e.g., /usr/local/signet/.


3. Set JAVA_HOME - Set your environment variable to your local JDK directory.


4. Run the startup scripts, appropriately: .bat (for Windows) or .sh (for Mac/Unix).
        (...wait for Tomcat and the db server to start up.)


5. Connect to your own personal Signet instance:
   • Open a web browser and point to: http://localhost:8080/signet
   • At the prompt, enter: Username = [demo], Password = [signet].
   
   
6. To exit Signet, close the browser, then run ./shutdown.bat or ./shutdown.sh to shutdown both Tomcat and HSQLDB.


7. Run into an error? Check out our Troubleshooting tips.

Note that the QuickStart version of Signet is the full product, simply pre-configured and using an embedded HSQL database with pre-populated demo data. The following phases can be applied against this installation, if desired, to more fully customize or make site-specific your demo.

Phase III — Tomcat Configuration of your Signet Implementation

In this phase, you will create a "Signet" web application context in your servlet container, i.e., you will point the web application context (Tomcat) to the Signet/webapp directory provided in this v1.0 distribution. You will need to choose one of two methods for doing so:

• directly copy the Signet/webapp folder over to the Tomcat directory (the Quickstart release does this), OR
• reconfigure Tomcat to point to where Signet resides.

In the following discussion, TOMCAT_PATH refers to the directory path that contains your Tomcat instance, while SIGNET_PATH refers to the directory path where you downloaded Signet.

To Copy:

Copy SIGNET_PATH/webapp/signet to the TOMCAT_PATH/webapps/ folder, e.g.,

cp -r /usr/local/signet/webapp/signet /usr/local/tomcat/webapps/

or using Windows Explorer or other desktop methods.

To Reconfigure:

You will need to update the Tomcat server configuration file to point to the signet/webapp/signet directory: Open Tomcat/conf/server.xml, and insert the following <Context>...</Context> within (at the end of) the <Host>....</Host> tag:

     <Context path="/signet"
          docBase="SIGNET_PATH/webapp/signet"
          crossContext="false"
          debug="9"
          reloadable="false" >
     </Context>
        

replacing SIGNET_PATH with the path leading your Signet location, e.g., "/usr/local/signet/webapp/signet".

Phase IV — Set up the Database

The bundled Signet-Quickstart comes with an embedded and pre-loaded hsql database. A full installation anticipates that you will ultimately provide a database of your choice:

Execute the DDL appropriate for your database. The DDL (Data Definition Language) for each supported database is found in the signet/sql/ directory. Signet currently provides DDL for:

• HSQL
• Oracle
• Postgres
• Sybase

Use an interactive tool of your choice to execute the DDL such as dbArtisan for Windows, Aqua for Mac, or a database provided utility, e.g., sqltool for HSQL or isql for Sybase, etc. Refer to the Spec Sheet for more information.

Note: If using the Signet-Quickstart, and you decide to use your own database, it is recommended that you reload Signet in a browser after each change, to verify the success of any changes you have made.

Phase V — Configuring your Database Connection

Database access is through a JDBC driver, which is database specific. An appropriate driver must be installed in two places, as there are two parts to Signet that operate independently – the Web application and the utilities.

Copy your JDBC driver to two directories:

• signet/lib
• signet/webapp/signet/WEB-INF/lib -or-
  TOMCAT_PATH/webapps/signet/WEB-INF/lib (per Phase III)

You will need to configure your database connection in two locations – open the following XML files:

• signet/config/hibernate.cfg.xml
• signet/webapp/signet/WEB-INF/classes/hibernate.cfg.xml -or-
  TOMCAT_PATH/webapps/signet/WEB-INF/classes/hibernate.cfg.xml (per Phase III)

Set the connection parameters in this section of the file:

     <!-- Database connection properties -->

     <property name="hibernate.dialect">
          @DB_DIALECT@
     </property>
     <property name="hibernate.connection.driver_class">
          @DB_DRIVER@
     </property>
     <property name="hibernate.connection.url">
          @DB_URL@
     </property>
     <property name="hibernate.connection.username">
          @DB_USERNAME@
     </property>
     <property name="hibernate.connection.password">
          @DB_PASSWORD@
     </property>
      

Set Hibernate logging level

Edit the config/log4j.properties file

copy this edited file to:

• webapp/signet/WEB-INF/classes/log4j.properties -or-
  TOMCAT_PATH/webapps/signet/WEB-INF/classes/log4j.properties (per Phase III)

Note: If using the Signet-Quickstart, and you decide to configure your own database server, it is recommended that you reload Signet in a browser after each change, to verify the success of any changes you have made.

Phase VI — Configuring your User Interface

The page header in the UI provides a space for your institutional logo or other graphic in the upper left corner of the screen. A pale "Your logo here" image is shipped with Signet. It should be replaced with an image of your choice. The layout is designed with a 60-pixel high image in mind.

signet/webapp/signet/images/site-logo.gif

Feedback URL

The page footer in the UI has an optional "Feedback" link that can point to your preferred email address.

Open the following file: signet/webapp/signet/tiles/footer.jsp

Change: <A href="@FEEDBACK_URL@" title="Signet Feedback">
        to: <A href="mailto:you@yourhost.edu" title="Your link name">

Use a null link value or eliminate the link altogether if you do not want this link to appear in your application.

Phase VII — Configuring your Subject Sources

• signet/config/sources.xml

• signet/webapp/signet/WEB-INF/classes/sources.xml

If you are using the local subject adapter, update the following parameters:

    <!-- Database connection properties -->
    <init-param>
      <param-name>dbDriver</param-name>
      <param-value>@DB_DRIVER@</param-value>
    </init-param>
    <init-param>
      <param-name>dbUrl</param-name>
      <param-value>@DB_URL@</param-value>
    </init-param>
    <init-param>
      <param-name>dbUser</param-name>
      <param-value>@DB_USERNAME@</param-value>
    </init-param>
    <init-param>
      <param-name>dbPwd</param-name>
      <param-value>@DB_PASSWORD@</param-value>
    </init-param>

See Phase V – Configuring your Database Connection for more information on these values.

Note: This file will also be used to declare your own Subject Source Adaptors. See the document on Extending & Integrating Signet for more information.

Phase VIII — Populating with Sample Data

A production implementation of Signet will be connecting to institutional data through data loads or real-time subject adapters. For the purpose of a successful installation, you may populate Signet with sample data.

To use the following utilities, your JAVA_HOME environment variable must be set to the location of your JDK. Note that it must point to a JDK - a JRE is not sufficient.

Note: To load real institutional data, a complete sample XML document offers a useful example that may be adapted to your local data. You may need to consult your Subsystem Owner/Business Analyst for the actual data.

Load the sample Organization-Tree data:

• Use the TreeXmlLoader to create the demo sample organization-tree by executing a util/TreeXmlLoader/ run script with the sample demo file, e.g.,
     > ./run.sh demo_tree.xml

Load the sample Subsystem data:

• Use the SubsystemXmlLoader to create the demo sample Subsystem by executing a util/SubsystemXmlLoader/ run script with the sample demo/data/Subsystem.xml file, e.g.,
     > ./ run.sh demo_biox_subsystem.xml
     > ./ run.sh demo_library_subsystem.xml

Load the sample Subject data:

• Modify the demo/data/Subject.txt file with any additional local Subject identities for your site.
• Use the SubjectFileLoader to to load that sample person data by executing a util/SubjectFileLoader/ run script with the sample demo/Subject.txt file, e.g.,
     > ./run.sh demo_subject.txt

Phase IX — Loading Signet

After you have downloaded the Signet distribution and reconfigured to customize your implementation (Phase II+), the next step is to point your browser to: http://localhost:8080/signet/. Be sure that your Tomcat instance or other servlet container is running, and also that your database server is available.

If you have configured Signet, JDK, Tomcat, and your database server (etc.) properly, you will be redirected to the Signet UI via an authentication prompt. At this point, you will enter a valid username [demo] and password [signet]. If you receive an error, see Troubleshooting below.

Troubleshooting

Verifying Tomcat

Start the Tomcat monitor. Open a web browser and access your server on port 8080, i.e., point the browser to: http://localhost:8080

If you have installed Tomcat properly, you will see the Apache Jakarta Project home page with the following message:

" If you're seeing this page via a web browser, it means you've setup Tomcat successfully. Congratulations! "

Once you have established that Tomcat is functional, you may wish to 'stop' Tomcat until after you finish installing Signet, at which point you will return to this step for the final loading of the Signet application.

If you receive an error or message other than the above:

» Is the database running?
» Have you entered the right username and password?
» Have you tried reloading Signet in your browser?

Other errors:

• "After I run the startup scripts, I receive an error message that "Windows cannot find -Djava.endorsed.dirs= . Make sure you typed the name correctly and then try again." I am currently using jre1.5.0_x and Windows XP."

» Signet says: Try setting your environment variable to: /jdk1.5.0_x (not /jdr). Run a search for "java.exe"; you should be able to view all the directories housing your /bin/java.exe, and then reset your environment variable to the 'jdk' directory, for JAVA_HOME.

Appendix

This section provides additional support and comments for running Tomcat. The information is intended to assist those not familiar with Tomcat, but is not meant to serve as a complete guide for Tomcat. Please contact your local IT for additional assistance if necessary.

Note that there are compatibility requirements between Java and Tomcat, for instance:

• for J2EE 1.4.2, select Tomcat 5.0.x
• for J2EE 1.5.0, select Tomcat 5.5.x

The Tomcat service (Windows) or daemon (unix, including Mac OSX) must be running to use the Signet application. Follow the startup and shutdown procedures in the Tomcat documentation.

You can verify that Tomcat is running on a machine by opening a web browser and accessing your server on port 8080; point to: http://localhost:8080. If you have installed Tomcat properly, you will see a page that informs you of the same. This step simply verifies that Tomcat is in a functional state of operation. Once you established that Tomcat is functional, you may wish to 'stop' Tomcat until you return for the final loading of the Signet application.