DCS War-Install-Windows.txt

Installing and Configuring from WAR file.



This procedure tested on Windows XP version 2002 service pack 2



1 - Obtain and install Tomcat (5.x) and Java (1.4.x or later) if necessary.

Setup information can be found at

	http://tomcat.apache.org/tomcat-5.5-doc/setup.html.



Tomcat for Windows installs as a "Service", which is a program running in the

background. For the purposes of installation and configuration, we DO NOT want

to run Tomcat as a service, instead we want to start and stop Tomcat manually.

To configure Tomcat,



a - use the Windows "Start" menu to find the Apache Tomcat 5.x configuration

utility 



	(Start -> All Programs -> Apache Tomcat 5.x -> Configure Tomcat)

	

b - Select the "General" tab and find the "Startup type" drop down menu. Select

"Manual".



c - Finally, look in the Windows "Tray" for the Tomcat service icon. If the icon is

found, right click it and then select "exit" in the menu. Now we have ensured

that no Tomcat processes are running and that we have manual control over

Tomcat. After DCS installation and configuration is complete, you may wish to

run Tomcat as a service, which you can do by reconfiguring tomcat to change the

"startup type" to "Automatic".



----------------------------------------------------------------------



NOTEs: 



- In this document, the top directory of your Tomcat installation will be

referred to as TOMCAT_HOME.



- Throughout this document, the notation ${FOO} is used 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 by EITHER:



a - double-clicking on the "tomcat5.exe" icon in ${TOMCAT_HOME}/bin, or by



b - executing ${TOMCAT_HOME}/bin/tomcat5.exe in a "Command Prompt" window.



When tomcat starts it unpacks the war file into a directory of the same name.

Startup may take a minute - you can monitor process in your command prompt

window. 



The following line in the output 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: At the top of the page you will see a message to the effect that the

	Sample Collection must be reindexed before it can be accessed. This is normal!

	There is no need to stop here and play with the sample collection, but 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 by entering

Ctrl-C in the Command Prompt window, and 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.



NOTES: 

a - Paths in the configuration file use a FORWARD SLASH instead of the windows

back slash. 



a - Don't forget to insert your values for ${TOMCAT_HOME} and ${DCS_NAME}

wherever they occur.



For example, if your TOMCAT_HOME directory was:



	C:\Program Files\Apache Software Foundation\Tomcat 5.5

	

then the following path:



	${TOMCAT_HOME}/webapps

	

would be expressed as follows in the configuration file:



	C:/Program Files/Apache Software Foundation/Tomcat 5.5/webapps





<!--  ----- 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="C:/Example/records/path"

			   	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="C:/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

smaple 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. You can

do so by clicking on the "OK" link below the message at the top of the screen or

you can follow steps a and b below.



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.



NOTE: do NOT click the "reindex" button for the Sample Collection,

as the entire index must be built at this time.



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 by

entering Ctrl-C into the Command Prompt window, and continue with configuration

step 5 above.