Installation

This document describes how to install the Registry software contained in the registry package. The following topics can be found in this section:

System Requirements

This section details the system requirements for installing and operating the Registry.

Java Runtime Environment

The Registry 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 (64-bit). The following commands test the local Java installation in a UNIX-based environment:

NOTE: This software only works with 64-bit Java installation.

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

Memory Requirements

      The Registry requires >2GB memory available in order to perform normal operations

Unpacking the Package

Download the registry package from the PDS FTP site. The binary distribution is available in identical zip or tar/gzip packages. The installation directory may vary from environment to environment but in UNIX-based environments it is typical to install software packages in the /home/pds directory and in Windows-based environments it is typical to install software packages in the C:\Program Files directory. Unpack the selected binary distribution file with one of the following commands:

The top-level directory where the package is installed will be referenced in these instructions as $REGISTRY_HOME.

% unzip registry-2.0.0-bin.zip
or
% tar -xzvf registry-2.0.0-bin.tar.gz

# Set the REGISTRY_HOME variable.
% cd registry-2.0.0

# On Linux and Mac
% export REGISTRY_HOME=$(pwd)

# On Windows
% set "REGISTRY_HOME=%cd%"

Note: Depending on the platform, the native version of tar may produce an error when attempting to unpack the distribution file because many of the file paths are greater than 100 characters. If available, the GNU version of tar will resolve this problem. If that is not available or cannot be installed, the zipped package will work just fine in a UNIX environment.

The commands above result in the creation of the registry-2.0.0 directory with the following directory structure:

  • LICENSE.txt

    The copyright notice from the California Institute of Technology detailing the restrictions regarding the use and distribution of this software. Although the license is strictly worded, the software has been classified as Technology and Software Publicly Available (TSPA) and is available for anyone to download and use.

  • README.txt

    A README file directing the user to the available documentation for the project.

  • VERSION.txt

    A VERSION file contains the version of the project.

  • bin/

    This directory contains the scripts for installing or uninstalling.

  • build/

    This directory contains the scripts for installing or uninstalling the project in Docker.

  • dist/

    This directory contains the jar for the Registry API (PDS Search Protocol).

  • conf/

    This directory contains the configuration for Apache Solr. This is where you can make updates to the Solr schema and solrconfig.xml.

  • lib/

    This directory contains the jars used by the Solr to parse XSLT.

Install Solr and Registry - Docker

NOTE: Docker installation is currently only available for Linux / Mac OS X users. We are working on a version for Windows. In the meantime, Windows Users please use the Standalone Installation

This section details how to install and deploy a dockerized instance of the PDS Registry.

Linux / Mac OS X - Docker

The following Registry installation procedure is for Linux and Mac operating systems. Please contact Engineering Node if you run into any issues.

  1. Install and Run Docker Desktop for Mac as indicated in Install Docker Desktop for Mac website if your system doesn't have Docker.

  2. Move to the directory that registry installer script resides. 
    % cd $REGISTRY_HOME/bin
  3. Execute a registry installer script. 
    % ./registry_install.sh
  4. Enter the install mode (docker). 
    Enter an installation mode (docker or standalone): docker

    You should see output similar to the following: 

    STARTING Registry Installer in docker mode.

  Registry   .....   
       ( v 2.0.0 )
       ( installing on platform: Mac OS X )
       ( IP Address:- 192.168.1.65 )
       ( Host Name:- MT-106917 )

Execute to install Registry in Docker...
Building Registry Docker Image.                               SUCCESS
Starting Registry Docker Container.                           SUCCESS
Waiting for Solr server to start (60 seconds)...
Creating a Registry Service Blob collection (.system)                SUCCESS
Creating a Registry Service XPath collection (xpath)                 SUCCESS
Creating a Search collection (pds)                           SUCCESS
Completed to install Registry in Docker.
  5. Verify installation.

    Open up your favorite browser and type in http://localhost:8983/solr. You should see the Solr admin interface.

Linux Users

    NOTE: Make sure that there is a Docker installation and up and running on the platform.

  1. Move to the directory that registry installer script resides. 
    % cd $REGISTRY_HOME/bin
  2. Execute a registry installer script. 
    % ./registry_install.sh
  3. Enter the install mode (docker). 
    Enter an installation mode (docker or standalone): docker

    You should see output similar to the following: 

    Enter an installation mode (docker or standalone): docker
STARTING Registry Installer in docker mode.

  Registry   .....   ( v 2.0.0 )
                           ( installing on platform: Linux )
                           ( IP Address:- 192.168.1.65 )
       					   ( Host Name:- pds )

Installing Registry in Docker...
Building Registry Docker Image.                               SUCCESS
Starting Registry Docker Container.                           SUCCESS
Waiting for Solr server to start (30 seconds)...
Creating a Registry Service Blob collection (.system)                SUCCESS
Creating a Registry Service XPath collection (xpath)                 SUCCESS
Creating a Search collection (pds)                           
Completed to install Registry in Docker.
  4. Verify installation.

    Open up your favorite browser and type in http://localhost:8983/solr. You should see the Solr admin interface.

Install Solr and Registry - Standalone

This section of the Registry Installation guide is for installing Solr and the Registry as a standalone application outside of Docker. The Docker installation method is the preferred method, however, the standalone version is acceptable in certain circumstances. Please consult Engineering Node if you have any questions about what installation method you should pursue.

Linux / Mac OS X - Standalone

  1. Download Solr

    Unpack SOLR pkg and set SOLR_HOME

                  % tar xvf solr-7.7.0.tgz
              % cd solr-7.7.0
              
              # Set SOLR_HOME
              % export SOLR_HOME=$(pwd)
              % echo $SOLR_HOME
              /home/pds/solr-7.7.0

    NOTE: The export command will be used to store the directory of the Solr installation.

  2. Move to the directory that registry installer script resides (Note: See above for configuring the REGISTRY_HOME variable or find out what that path represents.) 
                  % cd $REGISTRY_HOME/bin
  3. Execute the registry installer software: 
                  % ./registry_install.sh
  4. Enter the install mode and SOLR installation location that is done in previous step. 
                  Enter an installation mode (docker or standalone): standalone
              
              Enter location of SOLR installation: /home/pds/solr-7.7.0

    You should see output similar to the following: 

                  STARTING Registry Installer in standalone mode.
              
              Registry   .....   
              ( v 2.0.0 )
              ( installing on platform: Mac OS X )
              ( IP Address:- 192.168.1.65 )
              ( Host Name:- MT-106917 )
              
              Enter location of SOLR installation: /Users/pds/SOLR/solr-7.7.0 
              Copied a directory from /Users/pds/registry/target/registry-2.0.0/bin/../dist to /Users/pds/SOLR/solr-7.7.0/contrib/pds/lib
              Copied a directory from /Users/pds/registry/target/registry-2.0.0/bin/../conf to /Users/pds/SOLR/solr-7.7.0/server/solr/configsets/pds/conf
              Copied a file from /Users/pds/registry/target/registry-2.0.0/bin/../lib/saxon-9.jar to /Users/pds/SOLR/solr-7.7.0/server/solr-webapp/webapp/WEB-INF/lib/saxon-9.jar
              Copied a file from /Users/pds/registry/target/registry-2.0.0/bin/../lib/saxon-dom-9.jar to /Users/pds/SOLR/solr-7.7.0/server/solr-webapp/webapp/WEB-INF/lib/saxon-dom-9.jar
              
              Starting a SOLR server ....Waiting up to 180 seconds to see Solr running on port 8983....
              *** [WARN] *** Your open file limit is currently 10240.  
              It should be set to 65000 to avoid operational disruption. 
              If you no longer wish to see this warning, set SOLR_ULIMIT_CHECKS to false in your profile or solr.in.sh
              *** [WARN] ***  Your Max Processes Limit is currently 1418. 
              It should be set to 65000 to avoid operational disruption. 
              If you no longer wish to see this warning, set SOLR_ULIMIT_CHECKS to false in your profile or solr.in.sh
              Waiting up to 180 seconds to see Solr running on port 8983 [-]  
              Started Solr server on port 8983 (pid=67836). Happy searching!
              
              
              Return status from the SOLR server startup = 0
              The SOLR server is started successfully.
              Creating Registry Service collection (.system) ...
              {
              "responseHeader":{
              "status":400,
              "QTime":45},
              "Operation create caused exception:":"org.apache.solr.common.SolrException:org.apache.solr.common.SolrException: collection already exists: .system",
              "exception":{
              "msg":"collection already exists: .system",
              "rspCode":400},
              "error":{
              "metadata":[
              "error-class","org.apache.solr.common.SolrException",
              "root-error-class","org.apache.solr.common.SolrException"],
              "msg":"collection already exists: .system",
              "code":400}}
              Return status from creating registry service collection (.system) = 0
              Registry service collection (.system) is created successfully.
              {
              "responseHeader":{
              "status":0,
              "QTime":122}}
              Return status from creating registry service collection alias = 0
              Registry service collection alias (.system) is created successfully.
              Creating Registry Service collection (xpath) ...
              {
              "responseHeader":{
              "status":0,
              "QTime":3528},
              "success":{
              "192.168.1.65:8983_solr":{
              "responseHeader":{
              "status":0,
              "QTime":1881},
              "core":"xpath_shard1_replica_n1"}},
              "warning":"Using _default configset. Data driven schema functionality is enabled by default, which is NOT RECOMMENDED for production use. To turn it off: curl http://{host:port}/solr/xpath/config -d '{\"set-user-property\": {\"update.autoCreateFields\":\"false\"}}'"}
              Registry service collection (xpath) is created successfully.
              {
              "responseHeader":{
              "status":0,
              "QTime":120}}
              Registry service collection alias (xpath) is created successfully.
              Creating Search collection (pds) ...
              Created collection 'pds' with 1 shard(s), 1 replica(s) with config-set 'pds'
              Return status from creating search collection = 0
              Search collection (pds) is created successfully.
  5. Verify installation.

    Open up your favorite browser and type in http://localhost:8983/solr. You should see the Solr admin interface.

Windows - Standalone

  1. Install Curl

    If Curl is not already installed on the target Windows machine, it can be downloaded from the Curl website. Make sure that the PATH environment references the bin/ folder in the Curl directory(i.e. C:\path\to\curl\bin).

  2. Open Command Prompt via the 'Command Prompt' executable.

  3. Download Solr

    and unpack the zip file. Note this directory location.

    From Command Prompty, go to directory of unpacked Solr software, and output the full path for future reference:

                  $ cd solr-7.7.2
              
              # Set SOLR_HOME variable and note path that is output
              $ set "SOLR_HOME=%cd%"
              $ echo %SOLR_HOME%
              C:\home\pds\solr-7.7.0
  4. Now we go to where we unpacked the Registry, and move to the directory that registry installer script resides (See Unpacking the Package above.) 
                  $ cd %REGISTRY_HOME%\bin
  5. Execute Registry installer script. 
                  $ registry_install.bat
  6. Enter the install mode and SOLR installation location that is done in previous step. 
                  Enter an installation mode (docker or standalone): standalone
              
              Enter location of SOLR installation: C:\home\pds\solr-7.7.0

    You should see output similar to the following: 

                  STARTING Registry Installer in standalone mode.
              
              Registry   .....   
              ( v 2.0.0 )
              ( installing on platform: Windows 7 )
              ( IP Address:- 192.168.1.65 )
              ( Host Name:- PDS-HP )
              
              Enter location of SOLR installation: C:\Users\pds\solr-7.7.0
              Copied a directory from C:\Users\pds\registry-2.0.0\bin\..\dist to C:\Users\pds\solr-7.7.0\contrib\pds\lib
              Copied a directory from C:\Users\pds\registry-2.0.0\bin\..\conf to C:\Users\pds\solr-7.7.0\server\solr\configs
              ets\pds\conf
              Copied a file from C:\Users\pds\registry-2.0.0\bin\..\lib\saxon-9.jar to C:\Users\pds\solr-7.7.0\server\solr-w
              ebapp\webapp\WEB-INF\lib\saxon-9.jar
              Copied a file from C:\Users\pds\registry-2.0.0\bin\..\lib\saxon-dom-9.jar to C:\Users\pds\solr-7.7.0\server\so
              lr-webapp\webapp\WEB-INF\lib\saxon-dom-9.jar
              
              Starting a SOLR server ....Waiting up to 180 seconds to see Solr running on port 8983....
              SOLR server is started on Windows 7
              Creating Registry Service collection (.system) ...
              {
              "responseHeader":{
              "status":0,
              "QTime":11259},
              "success":{
              "169.254.193.90:8983_solr":{
              "responseHeader":{
              "status":0,
              "QTime":7562},
              "core":".system_shard1_replica_n1"}},
              "warning":"Using _default configset. Data driven schema functionality is enabled by default, which is NOT RECOMMENDED for production use. To turn it off: curl http://{host:port}/solr/.system/config -d '{\"set-user-property\": {\"update.autoCreateFields\":\"false\"}}'"}
              Return status from creating registry service collection (.system) = 0
              Registry service collection (.system) is created successfully.
              {
              "responseHeader":{
              "status":0,
              "QTime":384}}
              Return status from creating registry service collection alias = 0
              Registry service collection alias (.system) is created successfully.
              Creating Registry Service collection (xpath) ...
              {
              "responseHeader":{
              "status":0,
              "QTime":17582},
              "success":{
              "169.254.193.90:8983_solr":{
              "responseHeader":{
              "status":0,
              "QTime":13858},
              "core":"xpath_shard1_replica_n1"}},
              "warning":"Using _default configset. Data driven schema functionality is enabled by default, which is NOT RECOMMENDED for production use. To turn it off: curl http://{host:port}/solr/xpath/config -d '{\"set-user-property\": {\"update.autoCreateFields\":\"false\"}}'"}
              Registry service collection (xpath) is created successfully.
              {
              "responseHeader":{
              "status":0,
              "QTime":355}}
              Registry service collection alias (xpath) is created successfully.
              Creating Search collection (pds) ...
              Created collection 'pds' with 1 shard(s), 1 replica(s) with config-set 'pds'
              Return status from creating search collection = 0
              Search collection (pds) is created successfully.
  7. Verify installation.

    Open up your favorite browser and type in http://localhost:8983/solr. You should see the Solr admin interface.

Common Errors

Failed to create a registry service collection (.system)...

This issue could happen for several reasons, but we will need to look through the logs to determine the issue:

  • Look at Solr Console log to determine where the issue may lie: 
    # STANDALONE INSTALLATION
open $SOLR_HOME/server/logs/solr.log
open $SOLR_HOME/server/logs/solr-8983-console.log
  • If the log output states: 
    Error occurred during initialization of VM
Could not reserve enough space for 2097152KB object heap
    TBD solution

HTTP 404 - Requested Resource Not Available

This error means the application failed to install correctly. The following are potential mitigation strategies:

  • Verify domain and port are correct for the local Solr installation.
  • View $SOLR_HOME/server/logs/solr.log for information on potential causes of the failed deployment.

Other Errors

For other errors that arise while testing the installation, see the Operate - Common Errors