Community:NCS/documentation/installdocs

From NSDLWiki

The Digital Collection System (DCS) can be used to generate and manage metadata collections based on XML schemas. The DCS is web-based, supporting distributed collections management with protection against concurrent editing and a roles-based permissions scheme. The DCS was originally developed as, and is currently used as, the collection management tool for the Digital Library for Earth System Education (DLESE).

The NCore version of the DCS (NCS) offers the ability to manage Digital Collections directly in the NSDL Data Repository (NDR). The NCS is currently used by the NSDL to manage digital collections in the NDR.

The software runs in a servlet container such as Apache Tomcat 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.

This procedure tested on LINUX, WindowsXP and MacOS v10.3

1 - Obtain and install Tomcat (5.5.x) and Java (1.5.x) if necessary. The Tomcat distribution provides instructions within the RUNNING.txt file.

In this document, your Tomcat installation directory will be referred to as $TOMCAT.

2 - Place the war file (ncs.war) in the webapps directory ($TOMCAT/webapps). Start/restart Tomcat to unpack the war files and install the web application.

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/logs/catalina.out

3 - Access the system with your browser at http://localhost:8080/ncs. You will land on the NCS "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 you may do so after navigating to the "Manage -> Manage Collections" page and selecting the "Reindex" link for Sample Collection.

4 - Configure your NCS Application. A template Context Descriptor (context_descriptor_template.txt) in the distribution directory and also in the docs/templates directtory of the exploded war file. Configuration parameters include those necessary for your NCS to communicate with the NDR.

The Context Descriptor template lists the configuration parameters for the NCS. It describes thier usage and suggests values. Copy and edit the context_descriptor file as desired, and then place it either within $TOMCAT/conf/server.xml or at $TOMCAT/conf/Catalina/localhost/ncs.xml.

Restart Tomcat to apply your configurations.

When Tomcat has started, navigate to "Settings -> Indexings" and select the "Reindex All" button to ensure the index has been properly initialized. This action is only necessary when the location of the index and/or metadata files has changed since the last system startup.

5 - Set up User Roles and Permissions (Optional) This optional step allows you to define Authenticated users and to assign them a role, which defines the actions they have permission to carry out. Roles are used to control access to:

• Collections
• System functionality

There are two steps to enable the roles and permissions mechanism:

a - The "authenticationEnabled" parameter must be set to "true" in the context descriptor.

b - A parameter must be passed to the JVM when it is invoked (i.e., when Tomcat starts). This paramter tells the JVM where to look for the java class necessary to support user authentication at login ($NCS_CONF corresponds to a parameter defined in the Context Descriptor).

-Djava.security.auth.login.config==$NCS_CONF/auth/filelogin.config"

In UNIX, the recommended method for passing the required parameter is via a shell script that will start and stop Tomcat (and can be called by an system init script if desired). A template for script file can be found at templates/ncs.sh.template. The template contains the neccesary instructions for customizing it to your installation.

For WINDOWS, the recommended method is to pass the parameter via the "Apache Tomcat Properties" tool (found at $TOMCAT/bin/tomcat5w.exe). After opening the properties tool, click on the "Java" tab. Add the following line to the "Java Options" pane (after first replacing $TOMCAT with the full path to your tomcat installation: -Djava.security.auth.login.config==$TOMCAT\auth\filelogin.config

Restart Tomcat to apply your change. When try to access the NCS you will be challenged for a username and password. Use the following: username: root password: root!pass

Create and modify users via "Manage -> Manage Users", and specify their access to collections via "Manage -> Assign Collection Access"

NOTE: It is strongly suggested that you change the root user's password!

6 - Configure to communicate with the NDR Set the NDR configuration parameters in the context descriptor:

Note: The values for ndrServer and ncsAgentHandle must be obtained from the NDR administrators (ndr-users@comm.nsdl.org).

- ndrServiceEnabled - must be "true" to enable ndr service

- ndrServer - NDR Server - e.g. ndr.nsdl.org

- ncsAgentHandle - Handle of NDR Agent Object for this application

- ncsAgentPrivateKey - path to private key file associated with the ncsAgent. The NDR administrators can assist you with creating a private key file.

7 - Configure to activate the CAT (Content Alignment Tool) (Optional)

CAT is a service that suggests ASN (Achievement Standards Network) Education standards that may be supported by a particular resource. It uses natural language process techniques to process the resource content (the content of the web resource pointed to by a the resourceURL) to determine potentially relevant standards from the NSES (National Science Educational Standards). The suggested standards may then be accepted or rejected by the cataloger.

The CAT service is configured for a particular field within a particular framework. For example, the service might be configured for the asnID field of the "ncs_item" framework. The configuration can specify a single ASN Standards document from which the CAT service will make suggestions, or the configuration can specify a directory containing several ASN Standards documents from which suggestions will be made.

The suggestion service is configured via a single XML file as described below.

The suggestion service configured for a particular framework will apply to each of the collections belonging to that framework. However, the service may be disabled or enabled on a per-collection basis via the "Settings -> Collection-Settings" page. After navigating to the setting for a particular collection, edit the "allowSuggestions" field to either allow or disallow suggestions. By default, suggestions are allowed.

Suggestion Service Configuration details

There are two ways to activate the standards suggestion service

1 - Quick Configuration - Used to specify a single ASN Standards document to be used with the ncs_item framework.

Set the value for the "asnStandardsDocument" in the context descriptor must correspond to a file containing the NSES Standards in XML form. This file must reside on the local file system. The Standards Document must be obtained from The Achievement Standards Network (http://www.thegateway.org/asn/licensing-resources-and-services).

2 - Full Configuration - Used to configure one or more frameworks with different Standards Documents. In the full configuration each framework is configured by specifying:

- the framework (NOTE: a framework-specific plugin is required. If you would like to configure the suggestion service for a framework that does not yet have a plugin, please contact us via the form at http://nsdl.org/about/contactus/)

- the xpath of the metadata field for which suggetions will be made

- the Standards Documents from which suggetions will be made. NOTE Standards Documents must be obtained from The Achievement Standards Network (http://www.thegateway.org/asn/licensing-resources-and-services).

An example standards Configuration file can be found at templates/standardsSuggestionConfig.xml. To complete the configuration, perform the following steps,

a - copy and modify the standardsSuggestionConfig.xml file, and save it to disk.

b - set the value for the "standardsSuggestionServiceConfig" parameter in the context descriptor to point to the config file. NOTE: if a value for the "standardsSuggestionServiceConfig" is provided, the "asnStandardsDocument" parameter (used for the quick configuration option) is ignored.