Java Runtime Environment

The Registry Service was developed using Java and will run on any platform with a supported Java Runtime Environment (JRE). The software was specifically compiled for and tested in Java version 1.8. The following commands test the local Java installation in a UNIX-based environment:

% which java
/usr/bin/java

% java -version
java version "1.8.0_101"
Java(TM) SE Runtime Environment (build 1.8.0_101-b13)
Java HotSpot(TM) 64-Bit Server VM (build 25.101-b13, mixed mode)
        

The first command above checks whether the java executable is in the environment's path and the second command reports the version. If Java is not installed or the version is not at least 1.8, Java will need to be downloaded and installed in the current environment. Consult the local system administrator for installation of this software. For the do-it-yourself crowd, the Java software can be downloaded from the Oracle Java Download page. The suggested software package is the Java Standard Edition (SE) 8, either the JDK or the JRE package. The JDK package is not necessary to run the software but could be useful if development and compilation of Java software will also occur in the current environment.

Java Application Server

The Registry Service requires a Java application server for hosting the web application. The suggested application server for this release is Apache Tomcat with a minimal version of 7.0.X. Consult the local system administrator for installation of this software. For the do-it-yourself crowd, see the Tomcat Deployment document for installation and configuration details. If viewing this document from the registry-service package, view the Tomcat Deployment document from the Engineering Node site.

The top-level directory where Apache Tomcat is installed (i.e. the directory containing the webapps and conf sub-directories) will be referenced in these instructions as $TOMCAT_HOME.

cURL Utility

Although it is generally a useful tool for interacting with the Registry Service, the cURL command-line application is required by the RegistryConfig script for populating the service with the supported object types. See the Configuration section for more information on configuring the service. If cURL is not installed on the local server but Wget is, see the Using Wget section for converting cURL commands to Wget commands.

Database Server

The Registry Service comes prepackaged with the Apache Derby database. If another database solution is desired (i.e., MySQL), it should be installed and accessible by the Registry Service. See the Deploying the Database section if this is the first time you are installing the registry service and Configuration section for more information on configuring the service for a different database solution.

Derby

The Derby database comes packaged with the Registry Service. If choosing to utilize Derby as the database server, launch the Derby ij Tool as follows:

% cd registry-service-1.15.0
% java -Djava.ext.dirs=lib/ org.apache.derby.tools.ij
        

Then run each of the ij commands below to create the databases and install the registry schema:

ij> connect 'jdbc:derby:registrypds3;create=true;user=registry';
ij> run 'conf/derby-registry-schema.ddl';
ij> disconnect;
ij> connect 'jdbc:derby:registrypds4;create=true;user=registry';
ij> run 'conf/derby-registry-schema.ddl';
ij> exit;
        

The registrypds3 and registrypds4 directories, which are the Derby databases, will now be present in the current working directory. Note: For operational installations, the registrypds3 and registrypds4 directories should be moved to a more permanent location on disk that is accessible by Tomcat so that they don't get overwritten in a future upgrade. In addition, if the Tomcat server is not running as the root user, the registrypds3 and registrypds4 directories containing the Derby database (wherever it is located) must be owned by the same user account that is utilized to run the Tomcat server.

MySQL

If choosing to utilize an existing MySQL database server, perform the commands below. If installing a new instance of MySQL, consult the local system administrator for installation of this software. For the do-it-yourself crowd, the MySQL software can be downloaded from the MySQL Community Server Download page. Choose the appropriate package (version 5.5.X) for the target environment. Once the installation is complete, perform the commands below to create the databases and install the registry schema:

% cd registry-service-1.15.0
% mysqladmin -u root -p create registrypds3
% mysql -u root -p -e "GRANT ALL ON registrypds3.* TO registry@localhost \
  IDENTIFIED BY 'p@ssw0rd'"
% mysql -u root -p -D registrypds3 < conf/mysql-registry-schema.ddl
% mysqladmin -u root -p create registrypds4
% mysql -u root -p -e "GRANT ALL ON registrypds4.* TO registry@localhost \
  IDENTIFIED BY 'p@ssw0rd'"
% mysql -u root -p -D registrypds4 < conf/mysql-registry-schema.ddl
        

PostgreSQL

If choosing to utilize an existing PostgreSQL database server, perform the commands below. If installing a new instance of PostgreSQL, consult the local system administrator for installation of this software. For the do-it-yourself crowd, the PostgreSQL software can be downloaded from the PostgreSQL Download page. Choose the appropriate package (version 9.X) for the target environment. Once the installation is complete, perform the commands below to create the databases and install the registry schema:

% cd registry-service-1.15.0
% psql -U postgres
postgres=# CREATE USER registry WITH password 'p@ssw0rd';
postgres=# CREATE DATABASE registrypds3 WITH OWNER registry;
postgres=# \c registrypds3 registry
postgres=# \i conf/postgres-registry-schema.ddl
postgres=# \q
% psql -U postgres
postgres=# CREATE DATABASE registrypds4 WITH OWNER registry;
postgres=# \c registrypds4 registry
postgres=# \i conf/postgres-registry-schema.ddl
postgres=# \q
        

Database Configuration

The following is a set of instructions for configuring the Registry Service instances to access newly created or existing databases. The instructions are dependent on the database server to be used in the current environment.

Derby

By default, the Registry Service comes packaged with and configured to utilize Derby as the backend database. The default Derby configuration assumes that you have a database named registry and will use a default user name and password as specified below. In order to change the URL for the registry-pds3 instance of the service, edit the derby.properties file located in the $TOMCAT_HOME/webapps/registry-pds3/WEB-INF/classes directory. The following line:

javax.persistence.jdbc.url=jdbc:derby:registry

  should be changed to:

javax.persistence.jdbc.url=jdbc:derby:registrypds3
          

In order to change the URL for the registry-pds4 instance of the service, edit the derby.properties file located in the $TOMCAT_HOME/webapps/registry-pds4/WEB-INF/classes directory. The following line:

javax.persistence.jdbc.url=jdbc:derby:registry

  should be changed to:

javax.persistence.jdbc.url=jdbc:derby:registrypds4
          

The Derby database home directory will default to the current working directory where the Tomcat server was launched. To permanently set the home directory of the databases, add the following property to the CATALINA_OPTS environment variable:

CATALINA_OPTS="-Dderby.system.home=/path/to/registrydb/home"
          

Note: The derby.system.home should point to the parent directory which contains the registry databases (i.e. the parent directory of the registrypds3 and registrypds4 directories). See the Environment Configuration section of the Tomcat Deployment document for details on specifying the CATALINA_OPTS environment variable. If viewing this document from the registry-service package, view the Tomcat Deployment document from the Engineering Node site. The CATALINA_OPTS environment variable is loaded from the Tomcat startup scripts. The Tomcat server will need to be restarted for this configuration to take effect.

MySQL

If utilizing MySQL as the backend database, the configuration can be changed from Derby to MySQL. To modify the configuration for the registry-pds3 instance of the service, edit the applicationContext.xml file located in the $TOMCAT_HOME/webapps/registry-pds3/WEB-INF/classes directory. The following line:

<context:property-placeholder location="classpath:derby.properties"/>

  should be changed to:

<context:property-placeholder location="classpath:mysql.properties"/>
          

The default configuration assumes that you have MySQL installed with a database named registry and will use a default user name and password as specified below. In order to change the URL for the registry-pds3 instance of the service, edit the mysql.properties file located in the $TOMCAT_HOME/webapps/registry-pds3/WEB-INF/classes directory. The following line:

javax.persistence.jdbc.url=jdbc:mysql://localhost:3306/registry

  should be changed to:

javax.persistence.jdbc.url=jdbc:mysql://localhost:3306/registrypds3
          

To modify the configuration for the registry-pds4 instance of the service, edit the applicationContext.xml file located in the $TOMCAT_HOME/webapps/registry-pds4/WEB-INF/classes directory. The following line:

<context:property-placeholder location="classpath:derby.properties"/>

  should be changed to:

<context:property-placeholder location="classpath:mysql.properties"/>
          

In order to change the URL for the registry-pds4 instance of the service, edit the mysql.properties file located in the $TOMCAT_HOME/webapps/registry-pds4/WEB-INF/classes directory. The following line:

javax.persistence.jdbc.url=jdbc:mysql://localhost:3306/registry

  should be changed to:

javax.persistence.jdbc.url=jdbc:mysql://localhost:3306/registrypds4
          

Additionally for each instance, if you are using a version of MySQL older than 5.x you will need to change the dialect. To do this simply add a "#" before the first hibernate.dialect entry and remove the "#" from the second entry.

Before:

# For use with MySQL 5+
hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect
# For use with older versions of MySQL. See hibernate documentation.
#hibernate.dialect=org.hibernate.dialect.MySQLInnoDBDialect
          

After:

# For use with MySQL 5+
#hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect
# For use with older versions of MySQL. See hibernate documentation.
hibernate.dialect=org.hibernate.dialect.MySQLInnoDBDialect
          

PostgreSQL

If utilizing MySQL as the backend database, the configuration can be changed from Derby to PostgreSQL. To modify the configuration for the registry-pds3 instance of the service, edit the applicationContext.xml file located in the $TOMCAT_HOME/webapps/registry-pds3/WEB-INF/classes directory. The following line:

<context:property-placeholder location="classpath:derby.properties"/>

  should be changed to:

<context:property-placeholder location="classpath:postgres.properties"/>
          

The default configuration assumes that you have PostgreSQL installed with a database named registry and will use a default user name and password as specified below. In order to change the URL for the registry-pds3 instance of the service, edit the postgres.properties file located in the $TOMCAT_HOME/webapps/registry-pds3/WEB-INF/classes directory. The following line:

javax.persistence.jdbc.url=jdbc:postgresql://localhost:5432/registry

  should be changed to:

javax.persistence.jdbc.url=jdbc:postgresql://localhost:5432/registrypds3
          

To modify the configuration for the registry-pds4 instance of the service, edit the applicationContext.xml file located in the $TOMCAT_HOME/webapps/registry-pds4/WEB-INF/classes directory. The following line:

<context:property-placeholder location="classpath:derby.properties"/>

  should be changed to:

<context:property-placeholder location="classpath:postgres.properties"/>
          

In order to change the URL for the registry-pds4 instance of the service, edit the mysql.properties file located in the $TOMCAT_HOME/webapps/registry-pds4/WEB-INF/classes directory. The following line:

javax.persistence.jdbc.url=jdbc:postgresql://localhost:5432/registry

  should be changed to:

javax.persistence.jdbc.url=jdbc:postgresql://localhost:5432/registrypds4
          

Home Configuration

In a distributed environment with multiple Registry Service instances, the registry home value identifies the source of a registry entry when it has been replicated to another registry instance. By default, the registry home is configured as http://localhost:8080/registry. This should be modified to represent the Registry Service URL location of the local installation. Meaning that instead of localhost:8080, the fully qualified name of the local server should be specified (e.g., node.nasa.gov). To modify the configuration for the registry-pds3 instance of the service, edit the applicationContext.xml file located in the $TOMCAT_HOME/webapps/registry-pds3/WEB-INF/classes directory. Modify the following line with the new URL location:

<bean id="idGenerator"
class="gov.nasa.pds.registry.model.naming.DefaultIdentifierGenerator"
p:home="http://localhost:8080/registry"/>

  should be changed to (if hosted at node.nasa.gov on port 80):

<bean id="idGenerator"
class="gov.nasa.pds.registry.model.naming.DefaultIdentifierGenerator"
p:home="http://node.nasa.gov/registry-pds3"/>
        

To modify the configuration for the registry-pds4 instance of the service, edit the applicationContext.xml file located in the $TOMCAT_HOME/webapps/registry-pds4/WEB-INF/classes directory. Modify the following line with the new URL location:

<bean id="idGenerator"
class="gov.nasa.pds.registry.model.naming.DefaultIdentifierGenerator"
p:home="http://localhost:8080/registry"/>

  should be changed to (if hosted at node.nasa.gov on port 80):

<bean id="idGenerator"
class="gov.nasa.pds.registry.model.naming.DefaultIdentifierGenerator"
p:home="http://node.nasa.gov/registry-pds4"/>
        

Object Type Configuration

Once the Registry Service instances are installed and running, the list of supported object types must be registered with the services. The list of object types corresponds with the types of products that a given instance of the Registry Service will support. If this installation involves an existing database (where this configuration was previously performed), then the previous configuration must be deleted prior to loading the current version's configuration. If this is the case, follow the instructions in the Delete Existing Configuration section. Once the configuration packages have been deleted or if this is a new installation of the software, follow the instructions below for loading the configuration.

The registry-config and registry-config.bat scripts default to a Registry Service end point of http://localhost:8080/registry. In order to configure the registry-pds3 instance of the service, set the REGISTRY_SERVICE environment variable to the proper end point prior to executing the script. In addition, this script should be executed prior to applying security to the service URLs since it does not account for a secured interface. Execute the script from the bin directory in order to register the full set of object types:

% cd registry-service-1.15.0/bin
% export REGISTRY_SERVICE=http://localhost:8080/registry-pds3
% ./registry-config
        

In order to configure the registry-pds4 instance of the service, set the REGISTRY_SERVICE environment variable to the proper end point and execute the script:

% export REGISTRY_SERVICE=http://localhost:8080/registry-pds4
% ./registry-config
        

The output from these commands should show the registration of the Core object types and PDS object types. Since the configuration files referenced in the configuration script are slightly larger they are sent in chunks. Each configuration will get associated with a Registry Package and can be found by following the location link that comes in the header of the response. The output from the command should look something like the following:

* About to connect() to localhost port 8080 (#0)
*   Trying ::1... connected
* Connected to localhost (::1) port 8080 (#0)
> POST /registry/configure?name=Core+Objects&\
description=This+configures+the+core+set+of+registry+objects HTTP/1.1
> User-Agent: curl/7.19.7 ... libcurl/7.19.7 OpenSSL/0.9.8l zlib/1.2.3
> Host: localhost:8080
> Accept: */*
> Content-type:application/xml
> Content-Length: 5295
> Expect: 100-continue
>
< HTTP/1.1 100 Continue
< HTTP/1.1 201 Created
< Server: Apache-Coyote/1.1
< Location: http://localhost:8080/registry/packages/\
urn:uuid:bd6e4f7b-dfb0-443c-b845-3378077b1016
< Content-Type: text/plain
< Transfer-Encoding: chunked
< Date: Mon, 21 Mar 2011 19:55:52 GMT
<
* Connection #0 to host localhost left intact
* Closing connection #0
urn:uuid:bd6e4f7b-dfb0-443c-b845-3378077b1016

* About to connect() to localhost port 8080 (#0)
*   Trying ::1... connected
* Connected to localhost (::1) port 8080 (#0)
> POST /registry/configure?name=PDS+Objects&\
description=This+configures+PDS+object+types HTTP/1.1
> User-Agent: curl/7.19.7 ... libcurl/7.19.7 OpenSSL/0.9.8l zlib/1.2.3
> Host: localhost:8080
> Accept: */*
> Content-type:application/xml
> Content-Length: 18320
> Expect: 100-continue
>
< HTTP/1.1 100 Continue
< HTTP/1.1 201 Created
< Server: Apache-Coyote/1.1
< Location: http://localhost:8080/registry/packages/\
urn:uuid:a07ad134-42ad-4781-9cbd-826bb9a8dfec
< Content-Type: text/plain
< Transfer-Encoding: chunked
< Date: Mon, 21 Mar 2011 19:55:53 GMT
<
* Connection #0 to host localhost left intact
* Closing connection #0
urn:uuid:a07ad134-42ad-4781-9cbd-826bb9a8dfec
        

Verify successful configuration by executing the following command (where pdsX is either pds3 or pds4):

% curl -X GET -H "Accept:application/xml" -v \
http://localhost:8080/registry-pdsX/report
        

The output from this command should look something like the following (with respect to the classificationNodes and classificationSchemes attributes):

<ns2:report xmlns:ns2='http://registry.pds.nasa.gov' registryVersion='1.15.0'
packages='4' classificationNodes='67' classificationSchemes='2' services='0'
extrinsics='0' associations='69' serverStarted='2013-08-28T12:45:43.514-07:00'
status='OK'/>
        

Out of Memory

When deploying the application via the Tomcat Manager interface, users have occasionally encountered a situation where the application appears to hang or generates the following stack trace:

javax.servlet.ServletException: java.lang.OutOfMemoryError: PermGen space
  com.sun.jersey.spi.container...WebComponent.service(WebComponent.java:424)
  com.sun.jersey.spi.container...ServletContainer.service(ServletContainer.java:497)
  com.sun.jersey.spi.container...ServletContainer.doFilter(ServletContainer.java:855)
  com.sun.jersey.spi.container...ServletContainer.doFilter(ServletContainer.java:828)
  com.sun.jersey.spi.container...ServletContainer.doFilter(ServletContainer.java:789)
  org.springframework.orm.jpa.support.OpenEntityManagerInViewFilter.doFilterInternal
  (OpenEntityManagerInViewFilter.java:113)
  org.springframework.web...OncePerRequestFilter.doFilter(OncePerRequestFilter.java:76)
        

This is likely the result of not utilizing the suggested memory configuration for the Tomcat server specified in the Tomcat Deployment document. If viewing this document from the registry-service package, view the Tomcat Deployment document from the Engineering Node site. If the above situation occurs, verify the memory configuration and then stop and restart the Tomcat server to clear the problem.

Database Permission

When loading the Object Type Configuration for a Registry Service instance using Derby as the backend database, one will encounter the following error if the database directory is not owned by the user account that was used to launch the Tomcat server:

* About to connect() to localhost port 8080 (#0)
*   Trying ::1... connected
* Connected to localhost (::1) port 8080 (#0)
> POST /registry/configure?name=Core+Objects& \
description=This+configures+the+core+set+of+registry+objects HTTP/1.1
> User-Agent: curl/7.21.4 ... libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
> Host: localhost:8080
> Accept: */*
> Content-type:application/xml
> Content-Length: 6201
> Expect: 100-continue
>
< HTTP/1.1 100 Continue
< HTTP/1.1 409 Conflict
< Server: Apache-Coyote/1.1
< Content-Type: text/plain
< Transfer-Encoding: chunked
< Date: Thu, 24 Apr 2014 20:27:48 GMT
<
* Connection #0 to host localhost left intact
* Closing connection #0
[409 CONFLICT]   Registry object with logical id \
urn:uuid:626d5a54-6281-4579-ae5a-54dd962ade92 and version name 1.0 \
already exists.* About to connect() to localhost port 8080 (#0)
...
        

If the Tomcat server is not running as the root user, the registrypds3 and registrypds4 directories containing the Derby database (wherever it is located) must be owned by the same user account that is utilized to run the Tomcat server.