Setting up the HCL Commerce Solr-based Next.js store development environment

The Orchestration service acts as a bridge between Ruby applications that can only recognize Elastic-based search formats, and Solr-based search services. If you plan to develop for Ruby applications for use with a Solr-based search solution, you must configure the Orchestration service to test your storefronts in an HCL Commerce development environment.

For more information on the Orchestration service, see Orchestration service.

Before you begin

Before you can enable the use of the Orchestration service and test your site using the Solr-based search solution, you must:

Set up an HCL Commerce development environment:
- Install or upgrade to HCL Commerce Developer 9.1.16.0 or greater.
- Configure your HCL Commerce Developer Legacy environment for use with the Solr-based search solution. For more information on the Solr-based search solution, see Using Apache Solr as your search solution.
- Set up an HCL Commerce Developer Next.js Store environment.
Ensure that your environment meets both hardware and software requirements:
- For software requirements, review Supported software levels, fixes, and settings for HCL Commerce.
- For hardware requirements, review Hardware requirements for HCL Commerce.
- HCL Cache caches classes that can be modified in newer versions of HCL Commerce. To avoid errors in de-serializing an old version of the class, it is strongly recommended to clear Redis keys after upgrading HCL Commerce. Redis keys can be cleared with the Redis flushdb or flushall commands.
Configure Docker on Windows:
- If you are using Microsoft Windows: Configure Docker Desktop to support HCL Commerce’s resource and connectivity needs.
  1. Allocate Resources to Docker: HCL Commerce requires significant resources to run smoothly. These settings prevent performance issues with Solr and Orchestration containers.
    - To allocate:
      1. Open Docker Desktop.
      2. Click Settings > Resources > Advanced
      3. Set:
        
        CPUs: 8 cores
        
        Memory: 32 GB
        
        Disk Space: 80 GB
      4. Click Apply and Restart to save the changes and restart Docker.
  2. Enable Docker Daemon Access: This allows HCL Commerce tools to communicate with Docker. HCL Commerce requires quite a bit of resources to run smoothly. These settings prevent performance issues with Solr and Orchestration container.
    1. In Docker Desktop, go to Settings > General
    2. Check Expose daemon on tcp://localhost:2375 without TLS.
    3. Click Apply and Restart to save the changes and restart Docker.

Procedure

For HCL Commerce 9.1.16.1, patch and configure your HCL Commerce development environment.
1. Download and unzip the HCL Commerce 9.1.1.16.1 patch (HCL_Commerce_Config_9.1.16.1.zip).
  1. Log in to the My HCLSoftware portal.
  2. Locate and download HCL_Commerce_Config_9.1.16.1.zip.
  3. Extract the contents to a working directory.
2. Modify your HCL Commerce Developer installation.
  Open the WCDE_Installdir\workspace\search-ear\lib\ directory.
  1. Back up and delete the following files.
    - search-solr-ext-9.1.16.0-SNAPSHOT.jar
    - search-index-9.1.16.0-SNAPSHOT.jar
    - search-core-9.1.16.0-SNAPSHOT.jar
    - search-api-9.1.16.0-SNAPSHOT.jar
    - classic-foundation-stub-9.1.16.0-SNAPSHOT.jar
  2. Replace the files with those from the working patch directory, from within the workspace\search-ear\lib\ directory.
    - search-solr-ext-9.1.16.1-SNAPSHOT.jar
    - search-index-9.1.16.1-SNAPSHOT.jar
    - search-core-9.1.16.1-SNAPSHOT.jar
    - search-api-9.1.16.1-SNAPSHOT.jar
    - classic-foundation-stub-9.1.16.1-SNAPSHOT.jar
  3. Copy the configureSolrNextjsStore configuration utility from the patch into your HCL Commerce Developer installation.
    Move the toolkit\WCDE\bin\configureSolrNextjsStore.bat file into your WCDE_Installdir\bin\ directory.
3. Modify your Search server configuration.
  1. Open the Liberty_Installdir\usr\servers\searchServer\resources\search\runtime\config\com.ibm.commerce.search\ directory.
  2. Back up and replace the following three files with those that are contained within the searchServer\resources\search\runtime\config\com.ibm.commerce.search\ patch directory.
    - wc-component.xml
    - wc-query.tpl
    - wc-search.xml
  3. Back up and replace the Liberty_Installdir\usr\servers\searchServer\resources\search\runtime\config\com.ibm.commerce.rest\wc-rest-resourceconfig.xml configuration file with the copy from within the searchServer\resources\search\runtime\config\com.ibm.commerce.rest\ patch directory.
4. Modify your HCL Commerce Tooling SDK.
  1. Back up and replace the following two files with those that are contained within the toolkit\HCL-Commerce-Tooling patch directory.
    - commerce-tooling/proxy.conf.js
    - commerce-tooling/src/assets/config.json
Clone the HCL_Commerce_DevOps_9.1.x.x.bundle git bundle.
Ensure that your STORECONF database table is correctly configured.
- Ensure that wc.search.priceMode.compatiblePriceIndex is set to 0 for your store.
```
update storeconf set VALUE='0' where NAME='wc.search.priceMode.compatiblePriceIndex';
```
- For HCL Commerce 9.1.16.1 and 9.1.17.0: Follow these steps to configure Next.js with Solr-based search.
  - Ensure that hcl.imagePath is set to the image path for your store. For the default Next.js sample store, use the following SQL to set it to /hclstore.
    - INSERT INTO WCS.STORECONF (STOREENT_ID, NAME, VALUE) VALUES(41, 'hcl.imagePath', '/hclstore');
    - INSERT INTO WCS.STORECONF (STOREENT_ID, NAME, VALUE) VALUES(42, 'hcl.imagePath', '/hclstore');
  - Ensure that headlessStore is set to true for your store. For the default Next.js sample store, use the following SQL to set it to true.
    - INSERT INTO WCS.STORECONF (STOREENT_ID, NAME, VALUE) VALUES(41, 'headlessStore', 'true');
    - INSERT INTO WCS.STORECONF (STOREENT_ID, NAME, VALUE) VALUES(42, 'headlessStore', 'true');

Using the following env.sh configuration to enable orchestration within your HCL Commerce development environment.

SEARCH_ENGINE=solr 
DEPLOY_TYPE=toolkit 
REACT_STORE_ENABLED=false

LICENSE_ACCEPTED=accept 
ENV_TYPE=auth 

TOOLKIT_HOST=<toolkitHost> 
TOOLKIT_HOST_IP=<toolkitHostIP> 
TOOLING_HOST=<toolingHost>

ORCHESTRATION_ENABLED=true
ORCHESTRATION_IMAGE=<orchestrationImage> 

SPIUSER_PWD_ENCRYPTED=<encryptedSpiUserPassord>

Verify that all of the containers are up and healthy.
Run the HCL Commerce Developer Nextjs store configuration script.
1. Navigate to the WCDE_Installdir\bin\ directory.
2. Run the following command script.
```
configureSolrNextjsStore.bat orchestrationHost orchestrationPort nextjsStoreHost nextjsStorePort transactionHost transactionPort toolingSDKInstallDir nextjsStoreSDKInstallDir
```
  Where:
  
  orchestrationHost
  
  The hostname or IP address of the Orchestration server. Specifying localhost does not work.
  
  orchestrationPort
  
  The port number for the Orchestration server. For example, 19443.
  
  nextjsStoreHost
  
  The hostname or IP address of the Nextjs Store server. For example, localhost.
  
  nextjsStorePort
  
  The port number for the Nextjs Store server. For example, 3343.
  
  transactionHost
  
  The hostname or IP address of the Transaction server.
  
  transactionPort
  
  The port number for the Transaction server. For example, 443.
  
  toolingSDKInstallDir
  
  The installation directory for the Tooling SDK.
  
  nextjsStoreSDKInstallDir
  
  The installation directory for the Nextjs Store SDK.
  For example:
```
configureSolrNextjsStore.bat orchestration.commerce.com 19443 localhost 3343 localhost 443 C:\HCL_Commerce_Tooling C:\HCL_Commerce_Nextjs
```

Results

Your HCL Commerce development environment is now configured and deployed with the Orchestration service. You can now test Ruby applications using the Solr-based search solution.

What to do next

Enable the HCL Commerce Cache Manager application.

Note: the Cache Manager application can be deployed more easily by updating your deployment env.sh file and setting the CACHE_ENABLED and CACHE_APP_IMAGE parameters.