DCS War-Install.txt
Installing and Configuring from WAR file.

This procedure tested on LINUX and MacOS v10.3

1 - Obtain and install Tomcat (5.x) and Java (1.4.x or later) if necessary. The Tomcat
distribution provides instructions within the RUNNING.txt file. In this
document, the top directory of your Tomcat installation will be referred to as
TOMCAT_HOME.

NOTE: throughout this document, the notation ${FOO} is uses to imply that the
variable named inside the curly brackets (in this case, FOO) should be replaced
by its value. For example, if the value of FOO was /homes/jones/tomcat, then
everywhere a ${FOO} appears, you should replace it with /homes/jones/tomcat!

2 - Place the war file (schemedit-x.x.war) in the webapps directory
(${TOMCAT_HOME}/webapps). Rename it as you wish (but keep the .war extension).
The name you give the war file will become part of the base url used to access
all the pages of your DCS application. For example, if you name the war file
"myDcs", then the base url will be "http://localhost:8080/myDcs/". In this
document we will refer to the name you have chosen for your DCS as the DCS_NAME.

3 - Start tomcat

	${TOMCAT_HOME}/bin/startup.sh

When tomcat starts it unpacks the war file into a directory of the same name.
Startup may take a minute - if you want to monitor progress, you can watch the
log file using the following unix command:

	tail -f -n100 $TOMCAT_HOME/logs/catalina.out

The following line in the output from the above command signals that the system
is running and ready to access:

	INFO: Server startup in xxx ms

4 - Access the system with your browser at http://localhost:8080/DCS_NAME. You
will land on the "Collections" home page. 

	NOTE: The system has been loaded with a sample collection. There is no need to
	stop here and play with the sample collection, and in fact, doing so will
	require a few set-up steps in the DCS. If you want to try out the tool using the
	sample collection, see "Setting up the Sample Collection" at the end of these
	setup instructions.

Now it is time to configure your DCS installation. Stop Tomcat

	${TOMCAT_HOME}/bin/shutdown.sh

and get ready to edit some XML.

5 - First you will configure the security settings. These instructions assume
you want to protect (with username and password) your site for all users, and
place additional protection on the "Settings" area (with an admin username and
password).

There are two steps to configure the security settings:

A - Enable the security-contraints defined in the Deployment Descriptor File at

	${TOMCAT_HOME}/webapps/${DCS_NAME}/WEB-INF/web.xml 

Open the file and scroll to the bottom. The last two elements of the web.xml
file are "login-config" and "security-role". Above these elements are two
"security-constraint" elements - both of which are commented out, disabling
security.

	<!--
		<security-constraint>
				...
		</security-constraint>
	-->

Remove the comments surrounding both of the "security-constraint"
elements and save the file. (Carefull to remove only the comment tags
surrounding the security-constraint elements!)

B - The Tomcat-Users file defines roles, users and passwords for your DCS
instance. The Users file is located at

	${TOMCAT_HOME}/conf/tomcat-users.xml

Open this file in an editor. The tomcat-users file is populated with sample
definitions. Replace these with something like the following:

	<tomcat-users>
		<role rolename="admin"/>
		<role rolename="schemedit_admin"/>
		<user username="admin" password="adminpass" roles="admin,schemedit_admin"/>
		<user username="user" password="userpass" roles="schemedit_admin"/>
	</tomcat-users>

Save and close the file.

6 - At this point you may want to test your security settings. To do so, start
up Tomcat and access the Collections page as before. This time, you should be
challenged for a username and password. Use one of the combinations you defined
in tomcat-users. If you aren't allowed in then go back to step #5 and re-trace
your steps.

7 - Now you will configure the locations of some key system components. 

These locations default to directories inside the DCS application

	${TOMCAT_HOME}/webapps/${DCS_NAME}

but it is wise to move them outside of the application so that future installs and updates do not
write over them.

If tomcat is still running from step 6, please stop it now

Open up the Server Configuration file at 

	${TOMCAT_HOME}/conf/server.xml

 Again, scroll to the bottom of the file. There you will see the closing tags for (from bottom up)
the "Server", "Service", "Engine" and "Host" elements, e.g., 

		  </Host>
		</Engine>
	  </Service>
	</Server>

We will be adding to the "Host" element, so the text you will insert can be
placed just above the closing Host tag.

Cut and paste the following two elements ("Realm" and "Context") just above the
closing tag to the "Host" element. Change the parameter values for your
installation.

NOTE: Don't forget to insert your values for ${TOMCAT_HOME} and ${DCS_NAME}
wherever they occur.

<!--  ----- start cut and paste ----- -->

	<!-- tell tomcat that you will be using tomcat-users.xml as your 
		users database -->
	<Realm className="org.apache.catalina.realm.MemoryRealm"
	       pathname="conf/tomcat-users.xml" />
	
	<!-- parameters specifying the location of key system components -->
	
	<!-- docBase is the absolute path to the DCS application (the directory
			 that was created from the war file in step 3 -->
	<Context path="/${DCS_NAME}" 
		     docBase="${TOMCAT_HOME}/webapps/${DCS_NAME}"
			 reloadable="true" debug="0">

		<!-- Defines a label to use as the name of your DCS application. Replace
		the "myDCS" value with fan instance name for your installation. -->
			 
		<Parameter name="instanceName" 
				   value="myDCS"
				   override="false"/>

		<!-- Defines a "cataloger info" link that points to the specified URL,
		which can hold information for catalogers using this site. The contents
		of this link are the responsibility of the instance manager. The link
		will appear under the instance name at the top of all pages. Replace the
		empty value provided below with the url to your cataloger info, or leave
		the value blank to disable this feature -->
		<Parameter name="catalogingInfo" 
				   value=""
				   override="false"/>
						   
		<!-- The full path to your metadata records. Replace the value here with
		a path in your file system. If the path does not exist it will be
		created when the system starts up. -->
		<Parameter name="collBaseDir"
			   	value="/Example/records/path"
			   	override="false" />

		<!-- The path to the collection records. We strongly suggest that this
			path be the value of collBaseDir above, but add '/dlese_collect' 
			to the end -->
		<Parameter name="collectionRecordsLocation"
			   	value="/Example/records/path/dlese_collect"
			   	override="false" />
				
		<!-- The path to directory under which your collection and framework
		configuration files will go -->
		<Parameter name="dcsConfig"
			   	value="${TOMCAT_HOME}/dcs_config"
			   	override="false"/>
				
		<!-- The path to directory under which all exports will go. Replace the
		value below with one appropriate for your setup -->
		
		<Parameter name="exportBaseDir"
			   	value="/Example/exportBaseDir/path"
			   	override="false"/>

		<!-- location of your vocab files (see below). NOTE: this path must NOT
			end with a slash ("/") -->
		<Parameter override="false" 
			   	name="vocabConfigDir"
			   	value="${TOMCAT_HOME}/vocab-ui-project" />
	
	</Context>

<!--  ----- end cut and paste ----- -->
	
Save the file.

8 - As the last step, you will move the "vocab-ui-project" directory to the
location you specified in the preceeding step. We recommend you place this
directory in the TOMCAT_HOME directory, although it can go anywhere the file
system can find it.

	 cd ${TOMCAT_HOME}/webapps/${DCS_NAME}/WEB-INF/

	 mv vocab-ui-project ${TOMCAT_HOME} 

NOTE: the location you move the vocab-ui-project directory to must match the
"vocabConfigDir" path you specified in the Server Configuration (step #7)

9 - Start up Tomcat again. Now you are ready to create collections and populate
them with metadata records.

--------------------------------------------------------------------------------
Setting up the Sample Collection
--------------------------------

PLEASE NOTE: The sample collection and is intended for an introduction to the DCS only
- not for real use. After completing the configuration steps 5-9 above, you will
no longer have access to any collections or records you create in this
configuration will be inaccessible to the system after final configuration. So
you should regard any work you do here as expendible.

Before the sample collection can be accessed, the DCS index must be built:

1 - From the "Collections" page, go to Settings --> Collection Settings

a. First select the Settings Link at the top left of the page - this will open
the "DCS Settings" page

b. Choose the Collection Settings link in the horizontal menu below the "DCS
Settings" page heading

2 - click the "Reindex All" button at the bottom of the "Collection Settings"
page

a. Reindexing may take a few minutes. You can monitor progress by selecting the
"Check/refresh indexing status messages" link in the "Messages" box. 

3 - When the indexing is complete, you may navigate to the "Collections" or
"Search" pages and begin to explore the sample collection.

When you are ready to resume configuring your DCS for real use, stop Tomcat

	${TOMCAT_HOME}/bin/shutdown.sh
	
and continue with configuration step 5 above.