Setting up the Developer Solr-based Search environment

The HCL Commerce Developer Solr-based Search environment provides a modern development environment for customizing and debugging search functionality in HCL Commerce. It replaces the legacy IBM Rational Application Developer (RAD) based development environment for HCL Commerce Search (Solr V9) with a lightweight stack based on Maven, Open Liberty, and Eclipse. This toolkit only supports HCL Commerce Solr v9.10.1 Search environment. The existing HCL Commerce toolkit still provides a development environment based on Solr v7.

Following are the major key benefits:

Uses a standard Maven build (no proprietary scripts).
Runs on Open Liberty instead of WebSphere Liberty.
Enables hot deployment (changes are reflected without server restarts).
Ability to build and test customizaton with Java 17.

For more information on HCL Commerce Developer Solr-based Search environment, refer HCL Commerce Developer Solr-based Search environment.

Before you begin

OpenJDK 17: Download and install Java 17 (LTS) from: https://developer.ibm.com/languages/java/semeru-runtimes/downloads/
Open Liberty (26.0.0.4 Web Profile 8): Download from https://openliberty.io/start/#downloads-pkg
Eclipse IDE: Install Eclipse IDE for Enterprise Java and Web Developers (2024-06 or later). Install IBM Liberty Developer Tools from Eclipse Marketplace.
Maven: Install Maven3.9.x
Required features include: jsp-2.3, jaxrs-2.0, jpa-2.1, servlet-3.1, json-1.0, localConnector-1.0, distributedMap-1.0, webCache-1.0, appSecurity-2.0

Procedure

Obtain Solr-based Search docker images.
- Log in to the My HCLSoftware portal.
- Download:
```
HCL_Commerce_Enterprise_9.1.x.x_Search_Server_x86-64.tgz
```
Extract the Solr-based Search toolkit.
- Load the docker image:
```
docker load -i <HCL_Commerce_Enterprise_9.1.x.x_Search_Server_x86-64.tgz>
```
- Deploy a docker container, For example:
```
docker load -i HCL_Commerce_Enterprise_9.1.20.0_Search_Server_x86-64.tgz
```
- Run the container:
```
docker run -it --entrypoint bash --name search-app -d commerce/search-app:9.1.20.0
```
- Copy the toolkit:
```
docker cp search-app:/SETUP/bundles/search-bundle-*.zip
```
- Extract to a directory (referred to as <TOOLKIT_HOME>), for example:
```
C:\HCL\SearchToolkit
```
Set up the toolkit.
Windows:
```
cd <TOOLKIT_HOME>
.\setup-liberty.bat
```
Merge Liberty Resources: Copy the specialized directories from <TOOLKIT_HOME>/liberty/usr/ into your <LIBERTY_HOME>/usr/ directory. Ensure you include the extension/, shared/, and servers/searchServer/ folders.
1. extension/: Contains specialized HCL Commerce features required by the search server.
2. shared/: Contains shared libraries used by the EAR.
3. servers/searchServer/: The actual server profile
Install the required Liberty features.
After you copy the servers/searchServer/ directory into <LIBERTY_HOME>/usr/, install the features that are declared in the copied server configuration.
Windows:
```
cd <LIBERTY_HOME>\\bin
featureUtility.bat installServerFeatures searchServer
```
Linux or macOS:
```
cd <LIBERTY_HOME>/bin
./featureUtility installServerFeatures searchServer
```
Where searchServer is the Liberty server name under <LIBERTY_HOME>/usr/servers/searchServer. If you use a different server name, replace searchServer with that server name.
Build with Maven: Navigate to <TOOLKIT_HOME>/workspace/search-bundle and run mvn clean install.
Configuring the database and JNDI
After running the setup script, you must configure the connection details for your HCL Commerce database and environment. These configurations are located in the configDropins/overrides directory of the search server. This step ensures that the search server can connect to your database and can communicate with Store and Transaction servers.
1. (Oracle only) download Oracle jdbc jar place it under <openlibertyInstallDir>\wlp\usr\shared\resources\lib\oracle
2. Database configuration
  Update the database connection details to point to your DataBase.
  Edit the datasource configuration file
  <TOOLKIT_HOME>/liberty/usr/servers/searchServer/configDropins/overrides/datasources.xml
  Update the database properties
  Modify the following section to match your database configuration:
  DB2: <jdbcDriver id="db2_driver"> <library> <fileset dir="${shared.resource.dir}/lib/db2" includes="db2jcc4-4.27.25.jar"/> </library> </jdbcDriver> <properties.db2.jcc databaseName="DB_NAME" portNumber="DB_PORT" serverName="DB_HOST" user="wcs" password="{xor}ENCODED_DB_PWD"/>
  Oracle: <jdbcDriver id="oracle_driver"> <library> <fileset dir="${shared.resource.dir}/lib/oracle" includes="ojdbc8.jar"/> </library> </jdbcDriver> <dataSource isolationLevel="TRANSACTION_READ_COMMITTED" jdbcDriverRef="oracle_driver" jndiName="jdbc/wcdb" type="javax.sql.ConnectionPoolDataSource"> <properties.oracle URL="jdbc:oracle:thin:@//<DB_HOST>:<DB_PORT>/<DB_NAME>" databaseName="<DB_NAME>" password="{xor}YOUR_ECODED_DB_PWD" user="DB_USER"/> </dataSource>
  Where:
  
  DB_NAME - Name of your HCL Commerce database
  
  DB_PORT - Database port (default is usually 50000 for DB2, 1521 for Oracle)
  
  DB_HOST - Hostname of your database server
  
  DB_USER - Database user (for example, wcs)
  
  ENCODED_DB_PWD - XOR Encoded database password for the database user
3. Environment JNDI properties
  You must also configure the environment-specific endpoints used by the Search server.
  Edit the JNDI configuration file
  
  <TOOLKIT_HOME>/liberty/usr/servers/searchServer/configDropins/overrides/jndi.xml
  
  Update environment details
  Modify the hostnames and ports to match your environment for:
  
  Store server
  
  Transaction server
4. Solr Index Location (workAreaDir)
  By default, the toolkit is configured to store and build the Solr index within the toolkit's internal directory structure, workAreaDir → <TOOLKIT_HOME>/liberty/usr/servers/searchServer/resources/search. If you need to change the location where the search index is built (for example, to a larger disk or a custom development path), update the workAreaDir value in jndi.xml:
```
<jndiEntry jndiName="workAreaDir"
value="C:/Custom/Path/To/SolrIndex/resources/search"/>
```
Eclipse IDE setup:
This section guides you through setting up Eclipse to work with the Developer Solr-based Search environment and configuring the Liberty server for development and debugging.
1. Step 1: Workspace selection
  When launching Eclipse, choose the following directory as your workspace: <TOOLKIT_HOME>/workspace. We recommend using this workspace to ensure that all toolkit modules are correctly recognized and aligned with the project structure.
2. Configure Java 17 (critical)
  The toolkit requires Java 17 (especially for Solr 9 environments).
  1. Go to Window → Preferences → Java → Installed JREs.
  2. Add and select "JDK 17".
  3. Go to Java → Compiler and ensure the Compiler compliance level is set to 17.
3. Install Liberty tools (if missing)
  If you are using a fresh Eclipse installation, you must enable Liberty support.
  1. Go to Window → Preferences → Server → Runtime Environments.
  2. Select IBM → WebSphere Application Server Liberty Developer Tools (In older Eclipse versions, this may appear as “WebSphere Application Server Liberty Server Adapter”).
  3. Click Finish and close.
  This is a one-time setup. Once the Liberty feature is enabled, you can skip this step in the future and proceed directly to Step d.
4. Configure Liberty runtime
  Before creating a server, define the Liberty runtime in Eclipse.
  1. Go to Window → Preferences → Server → Runtime Environments.
  2. Click Add.
  3. Select IBM → Liberty Runtime, then click Next.
  4. Select “Choose an existing installation”.
  5. Browse to your<LIBERTY_HOME> directory (This should be the folder containing the wlp directory).
  6. Click Finish, then Apply and Close.
5. Import projects
  Import the toolkit projects into Eclipse.
  1. Go to File → Import → Maven → Existing Maven Projects.
  2. Browse to: <TOOLKIT_HOME>/workspace/search-bundle
  3. Select all modules and click Finish.
  4. Post-import steps (Important), ensure: Project → Build Automatically is checked.
  5. Right-click search-bundle → Maven → Update Project
    1. Select all modules
    2. Click OK
  6. Verify that the Problems view has no red errors.
6. Create the server
  Now create and configure the Liberty server in Eclipse.
  1. In the Servers view, right-click → New → Server
  2. Select: IBM → Liberty Server
  3. Choose the Liberty runtime configured in Step 4
  4. On the next screen, select the existing searchServer from the list.
  5. Click Finish.
    Note: The search-ear application is already mapped through the out-of-the-box configuration. No "Add/Remove" step is required.
  Optional: Adjust server timeout
  To avoid startup issues during initial runs:
  1. Double-click the server in the Servers view.
  2. Under Timeouts, increase the Start timeout to 300 seconds.

Integrate with HCL Commerce toolkit.

cd <WCDE_InstallDir>\bin
configureSolrSearchSDK.bat

(Optional) Update spiuser password.
Update the spiuser password if your organization requires custom credentials for security compliance, password rotation policies, or if you do not want to use the default generated password.
The password must match the value configured for the spiuser account and should be at least 45 characters long.
Default password:
```
QxV7uCk6RRiwvPVaa4wdD78jaHi2za8ssjneNMdu3vgqi
```
Command:
```
setSolrSearchSDKSpiuserPassword.bat open_liberty_install_dir spiuser_plain_text_password
```
Example:
```
setSolrSearchSDKSpiuserPassword.bat C:\openliberty\wlp MySecureSpiUserPasswordValue1234567890ABCDE
```

Running and debugging:


Action	Method
Start	Right-click server → Start
Debug	Right-click server → Debug
Hot swap	Save Java file (auto publish)