Digital Discovery System (DDS)
NSDL Search API Server (prod1)

Overview

These instructions describe how to install a DDS system in the Tomcat servlet container.

Installation Instructions

The following instructions describe how to install the pre-build DDS software from a WAR file. These instructions are also available in the file INSTALL_INSTRUCTIONS.txt that come with the DDS distribution:

=== Installation instructions for the Digital Discovery System (DDS) ===

DDS runs in a Tomcat servlet container and can be installed on 
Windows, Linux, Mac OS or UNIX systems. 

These instructions assume familiarity with Java Servlets, Java Server Pages (JSP), 
the Tomcat servlet container and related technologies.


To install DDS from a WAR file, do the following:
  
1. Obtain the dds.war file from the distribution.

2. Install Tomcat 5.5.x or 6.x and Java 1.5 or 1.6
Note that on some linux and unix distributions, Tomcat comes pre-installed but does not 
include all the required Java libraries. Download and install
a full copy of Tomcat directly from http://tomcat.apache.org/

3. Place the dds.war file in the ${tomcat}/webapps directory.

4. Edit the file ${tomcat}/conf/tomcat-users.xml in your Tomcat installation and
add the role 'dds_admin' and at least one user assigned to that role. This
restricts access to the Collection Manager and other admin pages in DDS.
		
	For example:
	
	<tomcat-users>
		<role rolename="dds_admin"/>
		... additional roles not shown ...
		
		<user username="jdoe" password="mypassword" roles="dds_admin"/>
		... additional users not shown...
	</tomcat-users>
	
5. Start/restart Tomcat to unpack the war files and install the DDS Web application.

6. See the deployment descriptor file ${tomcat}/webapps/dds/WEB-INF/web.xml for additional,
optional configuration options. Note that for a long-term operational deployment,
the context parameters 'indexLocation', 'collBaseDir' and 'repositoryData' should be
configured to point to local file directories OUTSIDE of tomcat.
These directories should be backed at regular intervals if repository 
data preservation is desired. A DDS repository may be restored using
a backup copy of these directories.

7. To configure the data source used for DDS, read the instructions provided in the DDS 
Web interface or the file CONFIGURE_DATA_SOURCES.txt.

Build Instructions

DDS is available as a pre-built WAR file (see above). However, if you wish instead to build DDS from source, please follow these instructions (BUILD_INSTRUCTIONS.txt):

  
=== Build instructions for the Digital Discovery System (DDS) ===

To install a pre-built version of DDS from a WAR file, see INSTALL_INSTRUCTIONS.txt.
If you wish to build the software from source, please follow the instructions
here.

These instructions assume familiarity with the Apache Ant build tool,
Java, CVS, and Tomcat.

The following are required to build and run the software from source:
-Java2 platform v5 or v6
-Ant build tool (http://ant.apache.org/)
-A CVS client of your choice

Optional:
-Tomcat version 5.5.x or 6.x (http://tomcat.apache.org/) (needed to deploy directly to Tomcat)


Build instructions:

1. Obtain the required source code modules from CVS:

	* dds-project - The DDS webapp context files, libraries and JSPs
	* dlese-tools-project - The Java source code
	* joai-project - Dependent code used to pull in OAI functionality	
	* frameworks-project - Dependent metadata vocabulary configuration files
	
	Each of the modules may be obtained from the DLS anonymous 
	CVS repository (sourceforge project dlsciences) here: 
	http://sourceforge.net/scm/?type=cvs&group_id=198325
	
	The modules are tagged with DDS release versions,
	for example 'dds_v3_3_14'. To obtain a specific version, 
	checkout all modules using the desired version tag.
	Supply no tag to obtain the latest development (HEAD) version.

2. Obtain and install Ant, Java, and optionally Tomcat (see above).

3. Place the required source code module directories into 
a single directory where you will be building the software.

4. Build or deploy the software

  --- Option 1: Generate a WAR file ---

* Execute the Ant 'war' target. You should see a number of messages 
in your terminal. Once complete you should see a message like:
    [echo] WAR file was created configured for data source 'fileSystem'
	BUILD SUCCESSFUL
    Total time: 1 minute 22 seconds
    
* If error messages appear, address the issues described and re-try 
until successful.
    
* The generated WAR file will have been saved to dds-project/war-distribution/dds.war

* Place the WAR file into the webapps directory of your Tomcat instance and start/restart
to launch the application in the container.


  --- Option 2: Deploy directly to a local Tomcat ---

* Create a file named build.properties in your home directory
(alternatively this may be placed in the dds-project directory).

* Edit the build.properties file to include the Ant properties that
are required for the build. These are listed at the top of the build.xml 
file at the root level of the dds-project.

* Execute the Ant 'deploy' target. You should see a number of messages 
in your terminal. Once complete you should see a message like:
    BUILD SUCCESSFUL
    Total time: 56 seconds
	
* If error messages appear, address the issues described and re-deploy
until successful.

* The software will be built into a directory named "dds" inside your
Tomcat webapps directory in the same manner as if it had been deployed
from a WAR file.

* Start/restart your tomcat instance to launch the application in the container


-- Additional notes ---

* See the build.xml file inside the dds-project for additional 
Ant targets that may be of interest.

* Follow the additional instructions for starting/stopping Tomcat and configuring DDS 
that are described in INSTALL_INSTRUCTIONS.txt and CONFIGURE_DATA_SOURCES.txt
University Corporation for Atmospheric Research (UCAR) National Science Foundation (NSF) National Science Digital Library (NSDL)