Deploying OpenSearch

OpenSearch is the open-source search engine and data store used to run the global search feature in NexJ CRM. You must install and configure OpenSearch before users can search for records across the application.

After installing OpenSearch, you need to integrate in into NexJ CRM. For more information, see Global search integration .

Software requirements for the global search feature

• The latest supported version of OpenSearch.

• OpenSearch Dashboards. Version associated with the OpenSearch distribution.

• OpenJDK. The version of JDK shipped with your release is recommended. To use a different Java installation, set the OPENSEARCH_JAVA_HOME or JAVA_HOME environment variable to the Java install location.

Deployment steps

You may need to install additional software, such as Docker and WSL, to complete the steps.

1. Install OpenSearch following the detailed steps described in the following topic: Installing OpenSearch - OpenSearch Documentation.

   • The recommended installation method is using Docker. For more information, see Docker - OpenSearch Documentation.

   • An alternative installation method for Linux is using a tarball. For more information, see Tarball - OpenSearch Documentation.

   • Installation on Windows from zip archive files:

     • Extract the provided archive files opensearch-2.18.0-windows-x64.zip and opensearch-dashboards-2.18.0-windows-x64.zip to the desired folders.

     • An OpenSSL executable is required to generate certificates for running OpenSearch with HTTPS and client certificate authentication. The executable is available from the Windows Subsystem for Linux (WSL) or third party software such as Cygwin.

     • (Optional) Proceed to test OpenSearch following the instructions at Windows - OpenSearch Documentation - Step 2: (Optional) Test OpenSearch.

     • Specify the desired minimum and maximum heap sizes in opensearch-2.18.0\config\jvm.options. A good starting point is to set both values to half of the available system memory, so set them to 4 GB if the host machine has 8 GB of memory.

2. Generate the self-signed certificate. For more information, see Generating self-signed certificates - OpenSearch Documentation. This certificate will be used for defining the es:Elasticsearch channel in the NexJ CRM environment file. When using the sample script described in the topic, in the “client cert” section, ensure that the value for CN is nexjesadmin and the value for subjectAltName is DNS:nexjesadmin. The sample script needs to be modified to run on Windows as a batch script. For example, change # to REM, remove the quotes around the string argument to the echo command, change rm to del.

3. For use on NexJ Model Server, the certificate must be in PKCS12 Base64 format. After running the sample script, run the following commands to generate the client certificate in that format. Enter a client certificate password when prompted and save it for future reference, as it will be needed when configuring the Elasticsearch channel in NexJ Studio.

   BASH

   openssl pkcs12 -export -in client.pem -inkey client-key.pem -out client.pfx -name client
   openssl base64 -in client.pfx -out client-base64.pfx

4. Enable client authentication following the instructions in Client certificate authentication - OpenSearch Documentation.

5. In opensearch-<version>/config/opensearch.yml, set the following to require client certificate authentication mode: plugins.security.ssl.http.clientauth_mode: REQUIRE

6. When updating opensearch-<version>/config/opensearch.yml for certificate settings, ensure the CN references the same names used during generation of the client certificate. Applicable settings include plugins.security.authcz.admin_dn and plugins.security.nodes_dn.

7. To enable auditing, follow the instructions included in Audit logs - OpenSearch Documentation.

8. Start the OpenSearch server and confirm that it starts up successfully.

9. Map the NexJ admin user to a role with admin access through the security configuration file. In the roles_mapping.yml file, under the all_access role, add:
   users: - "nexjesadmin"

10. As detailed in https://opensearch.org/docs/latest/security/configuration/security-admin/, run the following command from opensearch-<version> to initialize the security indexes (on Windows run securityadmin.bat instead):

    BASH

    cd ./plugins/opensearch-security/tools
    
    ./securityadmin.sh -cd ../../../config/opensearch-security/ -icl -nhnv -cacert ../../../config/root-ca.pem -cert ../../../config/admin.pem -key ../../../config/admin-key.pem

11. Restart the node for the security changes to take effect.

12. Follow the instructions for installing OpenSearch Dashboards at https://opensearch.org/docs/latest/install-and-configure/install-dashboards/index/.