Set up local development for Commerce Search v3 extensions

15 min

Connect your local development environment to the Sandbox Search Service to test Commerce Search v3 extensions against a real Search Service instance. This setup lets you verify custom pipes, handlers, and overrides on your own machine before you validate them in Sandbox.

Before you start, you need a provisioned Search Service, a local Elasticsearch v7 instance, and a copy of your Sandbox database. See Prerequisites.

Note

This setup supports the quick testing of Commerce Search v3 extensions.

It is not a complete Commerce Search v3 development environment.

Local development works only against the Sandbox environment, and your local environment shares the Sandbox Retail Search project. Review Limitations before you start.

How local development works

Commerce Search v3 uses the following two search back ends:

Google Cloud Retail Search (Retail Search) – Handles product search, browse, and autocomplete through the Commerce Search Service.

Your local application connects to the Sandbox Search Service.

You do not run a local Search Service, and Optimizely does not provision a separate Retail Search project for local development.

Elasticsearch v7 – Handles category search, product content search, and the supporting index. It runs on your local machine.

Your local database must match Sandbox.

This is because your local environment shares the Retail Search project of your Sandbox instance.

A full catalog rebuild indexes products into both back ends. Configure both for Commerce Search v3 to work as expected.

Prerequisites

Provisioned Search Service

Optimizely must provision Commerce Search v3 and the Search Service for your Commerce instance. Request provisioning through Optimizely Support, and allow several days for it to complete.

Until provisioning is complete, the Search Service tab in Mission Control shows that Search Service is not configured and displays no connection details.

Local Elasticsearch v7

Commerce Search v3 requires Elasticsearch v7 for category indexing, content indexing, and the search event repository.

If you use the repository's Docker configuration, run the following command to start Elasticsearch 7.10.2 on port 9200:

docker compose up -d elasticsearchv7

If you use your own Elasticsearch installation, confirm that the application can reach it, and note its URL for configuration.

Local database that matches Sandbox

Your local environment must use a copy of the same database as your Sandbox environment. Local development shares the Sandbox Retail Search project, which has the following effects:

Local indexing writes to the same Retail Search catalog that Sandbox uses.

Local searches query the same Retail Search catalog that Sandbox uses.

If your local database differs from Sandbox, the following problems occur:

Local indexing overwrites Sandbox catalog data.

Sandbox users see products from your local database.

Local searches return Sandbox products that do not exist locally.

Before you index, restore a current copy of the Sandbox database, and keep it synced with changes in Sandbox.

Get Search Service credentials

Get your connection details and generate credentials in Mission Control at Instance Detail > Integrations > Search Service.

See the Mission Control user guide for details about this tab.

Warning

Use values from your Sandbox instance only. Do not use credentials or connection details from Production or any other environment.

Copy the following values from the Search Service tab:

turnstileInstanceId

turnstileOrgId

turnstileProductId

projectId

Service URL

Select Generate New Credentials to create an App Key and App Secret.

These credentials expire after one week. When authentication starts to fail, generate credentials again.

Store the App Key and App Secret securely, and treat them like a password. Do not commit them to source control or share them outside your development team.

Configure your local environment

Where you add the configuration depends on how you run the application:

.NET 10 (Kestrel or Docker) – Add environment variables, typically in your .env file.

.NET Framework 4.8 (IIS) – Add appSettings entries in InsiteCommerce.Web/config/appSettings.config.

The key names are the same in both cases. Add the following keys with values from Mission Control and your local Elasticsearch instance:

Environment__ProjectIdentifier – The projectId value.

Environment__ElasticsearchNextServerUrl – Your local Elasticsearch URL, for example http://localhost:9200.

SearchService__ApiUrl – The Service URL value, without a trailing slash.

SearchService__AppKey – The App Key value.

SearchService__SecretKey – The App Secret value, exactly as Mission Control displays it.

Turnstile__InstanceId – The turnstileInstanceId value.

Turnstile__OrganizationId – The turnstileOrgId value.

Turnstile__ProductId – The turnstileProductId value.

Set both SearchService__AppKey and SearchService__SecretKey. If either is missing, the application starts, but every Search Service call fails with OptiCommerceSearch is not properly configured and may not be used.

Restart the application after you update the configuration.

Enable Commerce Search v3 locally

Turn on Commerce Search v3 on your local site so that search and indexing use the Search Service. See Enable Commerce Search v3 for details.

Go to Administration > System > Settings > Search > General on your local site.

Set Search Provider Name to Commerce Search v3.

Set Search Indexer Name to Commerce Search v3.

When you enable Commerce Search v3, the following settings change automatically:

Nested Documents Interaction – Off

Product Boosting – Off

Boosting by Purchase History – Off

Sponsored Search – Off

Category Autocomplete – On

Content Autocomplete – On

Brand Autocomplete – On

Product Autocomplete – On

Run a full index rebuild

Warning

A rebuild from your local environment updates the Retail Search catalog that Sandbox and other developers share. Coordinate rebuilds with your team.

Run a full catalog rebuild from Administration > Jobs. A successful rebuild logs the following stages:

Commerce Search v3 - Starting to index on Google Cloud Retail Search.
Commerce Search v3 - Completed indexing on Google Cloud Retail Search.
Commerce Search v3 - Starting to index on Elasticsearch v7.
Commerce Search v3 - Completed indexing on Elasticsearch v7.

Check the logs for warnings and errors, especially for Retail Search. Category and content indexing run only in local Elasticsearch v7, which is expected.

Validate the environment

Confirm the following behavior on your local storefront:

Product search returns results.

Category browsing works.

Autocomplete returns product, category, brand, and content suggestions.

Autocomplete suggestions depend on the volume of user events that Sandbox collects. When the volume is low, some suggestions do not display.

Limitations

Intended for extension testing

Use this setup for the following tasks:

Test custom search extensions.

Validate custom pipes, handlers, and overrides.

Verify request and response behavior against a real Search Service instance.

Do not use this setup for the following tasks:

Long-running Commerce Search v3 development

Search relevance tuning

Performance or load testing

Final release validation

Development that requires an isolated Retail Search index

Validate final changes in Sandbox before release.

Search Configurations not supported locally

The Search Service hosts the Search Configurations page as a separate front-end application that requires Opti ID authentication. Local development does not support this page.

Search Configurations is in Admin Console > Marketing > Commerce Search v3.

Use the Sandbox Admin Console to view and change Search Configurations settings. Changes you make in Sandbox also affect local search results, because both environments use the same Search Service tenant.

Shared Retail Search project

All developers who work against the same Commerce instance share one Sandbox Retail Search project. This sharing has the following effects:

A rebuild by one developer affects everyone.

A rebuild from a database that differs from Sandbox affects other developers and the Sandbox site.

Search configuration changes apply to all users immediately.

Recommended practices

Follow these practices to reduce the effect of local work on other developers and on Sandbox:

Coordinate index rebuilds with your team.

Keep local databases synced from the same Sandbox backup.

Avoid unnecessary rebuilds.

Use separate Commerce instances when multiple developers need isolated indexing environments.

Troubleshooting

The following list describes common symptoms, their likely causes, and how to resolve them:

OptiCommerceSearch is not properly configured and may not be used. – SearchService__AppKey or SearchService__SecretKey is missing. Add both keys, and restart the application.

Search Service rejects requests as unauthorized – The credentials expired, or the Turnstile values are incorrect. The Search Service returns 401 or 403. Generate credentials again, and check the Turnstile values against Mission Control.

Sandbox returns products that exist only locally – Your local database differs from Sandbox, and local indexing updated the shared catalog. Restore a current Sandbox database, and rebuild the index.

Local search returns products not stored locally – Your local site queries the shared Sandbox catalog. Restore a current Sandbox database to match the catalog.

Search results change unexpectedly – Another developer or Sandbox rebuilt the shared index.