Java Runtime Environment

The Registry Service was developed using Java and Jersey and will run on any platform with a supported Java Runtime Environment (JRE). The software was specifically developed under Java version 1.6 and has only been tested with this version. The following commands test the local Java installation in a UNIX-based environment:

% which java
/usr/bin/java

% java -version
java version "1.6.0_26"
Java(TM) SE Runtime Environment (build 1.6.0_26-b03-384-10M3425)
Java HotSpot(TM) 64-Bit Server VM (build 20.1-b02-384, 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.6, 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 software package of choice is the Java Standard Edition (SE) 6, 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 6.0.20 through version 7.0.X. Avoid version 7.0.29, there is a bug in this version causing an error when loading the Registry Service. 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.

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 machine 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.

Keep Existing Database

If the database is to be carried over to the upgraded installation, then the Deploying the Database section of this document should be skipped over but the following sections should be exercised as they would for a new installation with the exception that the configuration for the existing installation should be replicated in the upgrade:

• Deploying the Application
• General Configuration
• Secure Configuration

If the existing installation is version 1.3.0, then the database needs to be updated. The following is a set of instructions for creating the database and installing the registry schema that are dependent on the database server to be used in the current environment.

For a Derby database instance, execute the following commands to update the database to version 1.4.0 and beyond:

% cd registry-service-1.5.0
% java -Djava.ext.dirs=lib/ org.apache.derby.tools.ij
ij> connect 'jdbc:derby:registry;user=registry';
ij> run 'conf/registry-schema-upgrade-1.3.0.ddl';
ij> exit;
        

For a MySQL database, execute the following commands to update the MySQL database to version 1.4.0 and beyond:

% cd registry-service-1.5.0
% mysql -u root -p -D registry < conf/registry-schema-upgrade-1.3.0.ddl
        

For a PostgreSQL database, execute the following commands to update the PostgreSQL database to version 1.4.0 and beyond:

% cd registry-service-1.5.0
% psql -U postgres
postgres=# \c registry registry
postgres=# \i conf/registry-schema-upgrade-1.3.0.ddl
postgres=# \q
        

Delete Existing Database

If the determination was to not keep the existing database, then the database can be deleted. Prior to deleting the database, shutdown the Tomcat server. The following is a set of instructions for deleting the database that are dependent on the database server used in the current environment.

For a Derby database instance, execute the following to delete the database (the path was specified in the Configuration section):

% cd /path/to/registrydb/home
% rm -rf registry derby.log
        

For a MySQL database instance, execute the following to delete the database from the database server:

% mysqladmin -u root -p drop registry
        

For a PostgreSQL database instance, execute the following to delete the database from the database server:

% psql -U postgres
postgres=# drop database registry
postgres=# \q
        

Once the database has been deleted, see the Deploying the Database section for instructions on how to create a new database and install the registry schema. When the new database is in place, restart the Tomcat server. The following sections should then be exercised as they would for a new installation with the exception that the configuration for the existing installation should be replicated in the upgrade:

• Deploying the Application
• General Configuration
• Secure Configuration

Derby

The Derby database comes packaged with the Registry Service. The following commands will create the database and install the registry schema:

% cd registry-service-1.5.0
% java -Djava.ext.dirs=lib/ org.apache.derby.tools.ij
ij> connect 'jdbc:derby:registry;create=true;user=registry';
ij> run 'conf/derby-registry-schema.ddl';
ij> exit;
        

The registry directory, which is the Derby database, will now be present in the current working directory. The path to this directory can be specified in the Configuration section. Note: Feel free to move this registry directory to anywhere on disk that is accessible by Tomcat and configured below. In addition, if the Tomcat server is not running as the root user, the registry directory 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 database and install the registry schema:

% cd registry-service-1.5.0
% mysqladmin -u root -p create registry
% mysql -u root -p -e "GRANT ALL ON registry.* TO registry@localhost \
  IDENTIFIED BY 'p@ssw0rd'"
% mysql -u root -p -D registry < 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 database and install the registry schema:

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

Database Configuration

The following is a set of instructions for configuring the Registry Service to access an existing database that 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 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 database, 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 database (i.e. the parent directory of the "registry" directory). See the Tomcat Deployment document for details on specifying the CATALINA_OPTS environment variable. 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

The backend database can be changed from Derby to MySQL. To modify the configuration, edit the applicationContext.xml file located in the $TOMCAT_HOME/webapps/registry/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. If you want to change the URL, database name, user name, and/or password you will need to edit the mysql.properties file located in the $TOMCAT_HOME/webapps/registry/WEB-INF/classes directory. The following lines pertain to the default configuration:

javax.persistence.jdbc.url=jdbc:mysql://localhost:3306/registry
javax.persistence.jdbc.user=registry
javax.persistence.jdbc.password=p@ssw0rd
          

Additionally, 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

The backend database can be changed from Derby to PostgreSQL. To modify the configuration, edit the applicationContext.xml file located in the $TOMCAT_HOME/webapps/registry/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. If you want to change the URL, database name, user name, and/or password you will need to edit the postgres.properties file located in the $TOMCAT_HOME/webapps/registry/WEB-INF/classes directory. The following lines pertain to the default configuration:

javax.persistence.jdbc.url=jdbc:postgresql://localhost:5432/registry
javax.persistence.jdbc.user=registry
javax.persistence.jdbc.password=p@ssw0rd
javax.persistence.jdbc.driver=org.postgresql.Driver
hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
hibernate.hbm2ddl.auto=validate
jpa.database=POSTGRESQL
jpa.showSql=false
          

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, the fully qualified name of the local machine should be specified (e.g., node.nasa.gov). To modify the configuration, edit the applicationContext.xml file located in the $TOMCAT_HOME/webapps/registry/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"/>
        

Object Type Configuration

Once the Registry Service is installed and running, the list of supported object types must be registered with the service. The list of object types corresponds with the types of products that a given instance of the Registry Service will support. The registry-config and registry-config.bat scripts default to a Registry Service URL location of http://localhost:8080/registry. If necessary, modify the appropriate script for the local environment so that it corresponds with the URL location of the target installation. 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.5.0/bin
% ./registry-config
        

The output from this command 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 command from the Report section of the Operation document. The output from this command should look something like the following:

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