GDFR - Global Digital Format Registry
Welcome About GDFR GDFR Network Documentation Wiki Download Links

Global Digital Format Registry: Installing a mirror node

Preparation | Installation | Running your node

Preparation

System requirements

A GDFR mirror node can be installed on any Linux-based web server that meets certain system requirements. GDFR has been tested so far only on Linux systems, but it should also be installable on Unix. The following software is necessary to install a GDFR mirror. The versions given are minimum recommended versions. More recent versions should work, with one exception: Berkley XMLDB has to be exactly 2.3.10.

  • Tomcat 5.5.25
  • Apache 2.0.52 with mod_perl, mod_rewrite, mod_jk
  • Berkeley XMLDB 2.3.10
  • Java 1.5 JDK
  • Perl 5.8.5
  • Apache Ant 1.6.2
  • GCC 3.2 (for compling XMLDB only)

System set-up

apache

Throughout the rest of these instructions the parent apache directory (ex: /etc/httpd) will be called <APACHE_DIR>.

Make changes to httpd.conf (TODO: example)

mod_jk

mod_jk.so should be in <APACHE_DIR>/modules

Write a workers.properties file (TODO: example)

tomcat

Throughout the rest of these instructions the parent tomcat directory (ex: /usr/local/tomcat) will be called <TOMCAT_DIR>.

Make changes to server.xml

  • In the Connector element for the AJP 1.3 Connector add the attribute emptySessionpath=”true”. Example:
    <!– Define an AJP 1.3 Connector on port 8008 –>
    <Connector port=”8008”
    enableLookups=”false” redirectPort=”8443” protocol=”AJP/1.3” debug=”1”
    emptySessionPath=”true” />

Add lines in tomcat/bin/startup.sh to add the db libs to the LD_LIBRARY_PATH:
# set LD_LIBRARY_PATH to include berkeley xmldb libraries for gdfr
LD_LIBRARY_PATH=<DBXML_DIR>/install/lib
export LD_LIBRARY_PATH

dbxml

Throughout the rest of these instructions the parent dbxml directory (ex: /usr/local/dbxml) will be called <DBXML_DIR>.

User requirements

It is recommended that you create a user (e.g. gdfradm) that will own the GDFR directories. This user must be able to read and write to the tomcat webapps and conf directory, and all apache (at least conf, lib) and dbxml directories. This user must be able to start and stop tomcat and apache. The user needs to have the following environmental variables set:

  • JAVA_HOME
  • ANT_HOME (TODO: I don't think this is needed for mirror nodes)

Directory structure

Create a GDFR project directory with the following subdirectories. This directory will cbe called <GDFR_DIR> throughout the rest of these instructions.

  • stage_mirror (to install from)
  • deploy_mirror (to install to) (TODO: need to show the subdirectories they need to create)
  • schemas_mirror (TODO: don't think this is needed but would need to remove associated config property)
  • logs_mirror (for all installation and run-time log files - other than apache and tomcat logs)
  • config_mirror (to back up all GDFR, apache, tomcat configuation files)

Clean up (for re-installations only)

  • Delete the database data (<DBXML_DIR>/data/*)
  • Delete the web application directory (<TOMCAT_DIR>/webapps/webservices)
  • Copy your GDFR configuration files (config.example.properties, config.<username>.properties to your config_mirror directory, the delete the contents of your stage_mirror directory
  • Delete the contents of your deploy_mirror/scripts directory

Installation

1. Put the code into place

Download the tarball from http://www.gdfr.info/downlaod.html. Copy the tarball to your stage_mirror directory, and expand it there (tar xvzf gdfr-dist-tar.gz). You should then have a java subdirectory.

2. Configuration

After you expand the tarball you will see the GDFR example configuration file config.example.properties.

If this is a re-installation determine if you can reuse your config.<username>.properties file as is by running a diff comparing the new config.example.properties with the one you backed up during a previous installation. Ex: diff config.example.properties ../config_mirror/config.example.properties This will tell you what if any new configuration properties were added to this GDFR release. It is much easier to add any new properties to your backed up configuration fiel then to add all the property values again.

For new installation copy config.example.properties to config.<username>.properties where username is your GDFR user. For re-installations copy your backed up config.<username>.properties file to the stage_mirror directory.

Fill in the configuration values. The following are the variables you will most often have to customize. Where paths are mentioned, these are always full paths unless otherwise specified.

TODO: example values for each of these:

  • INSTALL_JAVA_HOME : Main directory of your Java JDK
  • INSTALLDIR : Path of deploy_mirror in the GDFR project directory
  • LOG_DIR : Path of logs_mirror in the GDFR project directory
  • SYSTEM_DATA_HOME : Location of your DBXML data home
  • SCHEMA_DIR : Path of schemas_mirror in the GDFR project directory
  • LIBPATH : Path of lib within the DBXML installation directory
  • APACHE_HOME : Path of the Apache installation, same as <APACHE_DIR>
  • APACHE_SHUTDOWN_COMMAND : Command to shut down Apache; may need to change httpd to the appropriate service name
  • TOMCAT_SHUTDOWN_COMMAND : Command line for the Tomcat shutdown script, usually shutdown.sh
  • APACHE_START_COMMAND : Command to start up Apache; may need to change httpd to the appropriate service name
  • TOMCAT_START_COMMAND : Command line for the Tomcat startup script, usually startup.sh
  • PERL_LIB_DIR : Path of Perl library directory
  • PERL_VERSION : Version of Perl in the library directory
  • SEARCH_MAX_RESULTS : Maximum number of search results returned
  • SOURCE_NODE_URL : The URL of the GDFR source node you are mirroring
  • AUTHENTICATE_URL : URL for the authentication service
  • AUTHORIZATION_URL : URL for the authorization service
  • COOKIE_CHECK_URL : URL for the cookie checking service
  • HTTP_PORT : HTTP port used by Apache
  • TOMCAT_HTTP_PORT : HTTP port used by Apache
  • TOMCAT_SHUTDOWN_PORT : Shutdown port for Tomcat
  • TOMCAT_AJP_PORT : Port for Tomcat AJP connector
  • CATALINAHOME : Path to Tomcat installation, same as <TOMCAT_DIR>
  • SHAREDPROFILEBASEURL : The base URL of your node
  • SMTPDOMAIN : Domain of your mail server (for sending notifications)
  • MAIL_NAME : E-mail name and address to appear in the From: field in notifications
Back up configuration files
  • Back up your config.<username>.properties and config.example.properties files to config_mirror
  • Back up apache and tomcat configuration files(<APACHE_DIR>/conf/httpd.conf, <APACHE_DIR>conf/app/*.conf, <TOMCAT_DIR>conf/server.xml, <TOMCAT_DIR>conf/jk/workers_properties

3. Deployment

  • cd to the the stage_mirror directory
  • Make deploy-app-oss executable (chmod u+x deploy-app-oss)
  • Run the script to build and deploy:
    ./deploy-app-oss <username> ../deploy_[nodetype] | tee ../logs/deploy-app-oss.log
  • Running this with the tee utility captures the output to a file as well as printing it to STDOUT
  • After this runs you should have:
    • a scripts/ directory of files in your deploy_mirror directory
    • a webservices/ directory of files in your tomcats’s webapps/ directory
    • sample configuration files:
      • httpd.conf.sample in your apache’s conf/ directory
      • server.xml.sample in your tomcat’s conf/ directory
  • replace the <TOMCAT_DIR>/webapps/webservices/WEB-INF/lib/db.jar and dbxml.jar with the ones from your dbxml (in <DBXML_DIR>/install/lib/)
  • check that you have a rewrite.conf file for apache. You may need to copy the rewrite.conf.sample file to rewrite.conf in your apache’s conf/app directory.
  • open a web browser to <BASEURL>/registry, where <BASEURL> is the base URL of your server.
  • Under the directory conf/tomcat/webapps/webservices/xsl/ there is a file called "config.xml" that has three fields. InstitutionName should contain the name of your respective institution. LogoPath should be the location of your institution's logo via a URL. Description should contain a brief description if your instution that will appear on the main page of the application.

4. Initializing your node

With Apache and Tomcat running, go to <GDFR_DIR>/deploy_mirror and run:
sh scripts/initialize-mirror-node.sh

Then restart the apache and tomcat servers.

Running your node

Synchronizing mirror node with the source node

To be written.

Setting up user accounts

To be written.