Skip to content

Commit

Permalink
Merge pull request #382 from AdobeDocs/COMDOX-425-elasticsearch8
Browse files Browse the repository at this point in the history 
COMDOX-425: Add doc updates for Elasticsearch 8 support
  • Loading branch information
@jeff-matthews
jeff-matthews authored and GitHub Enterprise committed Dec 21, 2022
2 parents e2dd2e7 + 58c70ac commit 33acb41
Show file tree
Hide file tree
Showing 2 changed files with 65 additions and 19 deletions.
41 changes: 25 additions & 16 deletions help/configuration/search/configure-search-engine.md
View file
@@ -1,33 +1,42 @@
---
title: Search engine configuration
description: Configure a search engine with Adobe Commerce and Magento Open Source.
description: Configure a search engine for on-premises deployments of Adobe Commerce and Magento Open Source.
---

# Search engine configuration

This section discusses the minimum settings that you must choose to test Elasticsearch or OpenSearch with Adobe Commerce and Magento Open Source. As of versions 2.4.4 and 2.4.3-p2, all fields labeled **Elasticsearch** also apply to OpenSearch.
This section discusses the minimum settings that you must choose to test Elasticsearch or OpenSearch with on-premises deployments of Adobe Commerce and Magento Open Source.

For additional details about configuring your search engine, see the [User Guide](https://docs.magento.com/user-guide/catalog/search-elasticsearch.html).
>[!TIP]
>
>In versions 2.4.4 and 2.4.3-p2, all fields labeled **Elasticsearch** also apply to OpenSearch.
>When support for Elasticsearch 8.x was introduced in version 2.4.6, new labels were created to distinguish between Elasticsearch and OpenSearch configurations.
For additional details about configuring your search engine, see the [User Guide](https://experienceleague.adobe.com/docs/commerce-admin/catalog/catalog/search/search-configuration.html).

## Configure your search engine from the Admin

>[!TIP]
>
>For instructions on upgrading to a new search engine version, see [upgrade prerequisites](../../upgrade/prepare/prerequisites.md).
To configure your system to use Elasticsearch or OpenSearch:

1. Log in to the Admin as an administrator.
1. Click **Stores** > Settings > **Configuration** > **Catalog** > **Catalog** > **Catalog Search**.
1. From the **Search Engine** list, select the corresponding version of your search engine If you are using OpenSearch, you must select Elasticsearch7.
1. Click **[!UICONTROL Stores]** > [!UICONTROL Settings] > **[!UICONTROL Configuration]** > **[!UICONTROL Catalog]** > **[!UICONTROL Catalog]** > **[!UICONTROL Catalog Search]**.
1. From the **[!UICONTROL Search Engine]** list, select the corresponding version of your search engine.

The following table lists the required configuration options to configure and test the connection with Commerce.
Unless you changed the server settings of your search engine, the defaults should work. Skip to the next step.
The following table lists the required options to configure and test the connection with Commerce. Unless you changed the server settings of your search engine, the defaults should work. Skip to the next step.

|Option|Description|
|--- |--- |
|**Elasticsearch Server Hostname**|Enter the fully qualified hostname or IP address of the machine running Elasticsearch or OpenSearch.<br>Adobe Commerce on cloud infrastructure: Get this value from your integration system.|
|**Elasticsearch Server Port**|Enter the web server proxy port. The default is 9200<br>Adobe Commerce on cloud infrastructure: Get this value from your integration system.|
|**Elasticsearch Index Prefix**|Enter the search engine index prefix. If you use a single instance for more than one Commerce installation (Staging and Production environments), you must specify a unique prefix for each installation. Otherwise, you can use the default prefix magento2.|
|**Enable Elasticsearch HTTP Auth**|Click **Yes** only if you enabled authentication for your search engine server. If so, provide a username and password in the provided fields.|
|**[!UICONTROL Server Hostname]**|Enter the fully qualified hostname or IP address of the machine running Elasticsearch or OpenSearch.<br>Adobe Commerce on cloud infrastructure: Get this value from your integration system.|
|**[!UICONTROL Server Port]**|Enter the web server proxy port. The default is 9200<br>Adobe Commerce on cloud infrastructure: Get this value from your integration system.|
|**[!UICONTROL Index Prefix]**|Enter the search engine index prefix. If you use a single instance for more than one Commerce installation (Staging and Production environments), you must specify a unique prefix for each installation. Otherwise, you can use the default prefix magento2.|
|**[!UICONTROL Enable HTTP Auth]**|Click **[!UICONTROL Yes]** only if you enabled authentication for your search engine server. If so, provide a username and password in the provided fields.|
|**[!UICONTROL Server Timeout]**|Enter the amount of time (in seconds) to wait when attempting to establish a connection to the Elasticsearch or OpenSearch server.|

1. Click **Test Connection**.
1. Click **[!UICONTROL Test Connection]**.

Sample response:

Expand Down Expand Up @@ -63,15 +72,15 @@ If so, try the following:
`tcp 0 0 :::9200 :::- LISTEN`
```

## Reindexing catalog search and refreshing the full page cache
## Reindex catalog search and refresh the full page cache

After you change the search engine configuration, you must reindex the catalog search index and refresh the full page cache using the Admin or command line.

To refresh the cache using the Admin:

1. In the Admin, click **System** > **Cache Management**.
1. Select the checkbox next to **Page Cache**.
1. From the **Actions** list in the upper right, click **Refresh**.
1. In the Admin, click **[!UICONTROL System]** > **[!UICONTROL Cache Management]**.
1. Select the checkbox next to **[!UICONTROL Page Cache]**.
1. From the **[!UICONTROL Actions]** list in the upper right, click **Refresh**.

![cache management](../../assets/configuration/refresh-cache.png)

Expand Down
43 changes: 40 additions & 3 deletions help/upgrade/prepare/prerequisites.md
View file
Expand Up @@ -53,13 +53,50 @@ Some third-party catalog search engines run on top of the Adobe Commerce search

### Elasticsearch

You must install and configure either Elasticsearch 7.6 or higher or OpenSearch 1.2 before upgrading to 2.4.0. Adobe no longer supports Elasticsearch 2.x, 5.x, and 6.x.
You must install and configure either Elasticsearch 7.6 or higher or OpenSearch 1.2 before upgrading to 2.4.0. Adobe no longer supports Elasticsearch 2.x, 5.x, and 6.x. [Configure Elasticsearch](../../configuration/search/configure-search-engine.md) in the _Configuration Guide_ describes the tasks you must perform after upgrading Elasticsearch to a supported version.

Refer to [Upgrading Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/setup-upgrade.html) for full instructions on backing up your data, detecting potential migration issues, and testing upgrades before deploying to production. Depending on your current version of Elasticsearch, a full cluster restart may or may not be required.

Elasticsearch requires JDK 1.8 or higher. See [Install the Java Software Development Kit (JDK)](../../installation/prerequisites/search-engine/overview.md#install-the-java-software-development-kit-jdk) to check which version of JDK is installed.
>[!INFO]
>
>Elasticsearch requires JDK 1.8 or higher. See [Install the Java Software Development Kit (JDK)](../../installation/prerequisites/search-engine/overview.md#install-the-java-software-development-kit-jdk) to check which version of JDK is installed.
#### Upgrade Elasticsearch

Support for Elasticsearch 8.x was introduced in Adobe Commerce and Magento Open Source 2.4.6. The following instructions show an example of upgrading Elasticsearch from 7.x to 8.x:

1. Upgrade the Elasticsearch 7.x server to 8.x and make sure that is is up and running. See the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html).
1. In the root directory of your Adobe Commerce or Magento Open Source project, update your Composer dependencies:

```bash
composer update elasticsearch/elasticsearch
```

1. Enable the `id_field_data` field by adding the following configuration to your `elasticsearch.yml` file and restarting the Elasticsearch 8.x service.

```yaml
indices:
id_field_data:
enabled: true
```

>[!INFO]
>
>To support Elasticsearch 8.x, Adobe Commerce and Magento Open Source 2.4.6 disallows the `indices.id_field_data` property by default and uses the `_id` field in the `docvalue_fields` property.
1. [Configure Elasticsearch](../../configuration/search/configure-search-engine.md#configure-your-search-engine-from-the-admin) to complete the upgrade.

#### Downgrade Elasticsearch

If you inadvertently upgrade the version of Elasticsearch on your server or determine that you need to downgrade for any other reason, you must also update your Adobe Commerce or Magento Open Source project dependencies.

1. In the root directory of your Adobe Commerce or Magento Open Source project, update your Composer dependencies. For example, to downgrade from Elasticsearch 8.x to 7.x:

```bash
composer update elasticsearch/elasticsearch:^7
```

[Configure Elasticsearch](../../configuration/search/configure-search-engine.md) describes the tasks you must perform after updating Elasticsearch 2 to a supported version.
1. [Configure Elasticsearch](../../configuration/search/configure-search-engine.md#configure-your-search-engine-from-the-admin) to complete the downgrade.

### OpenSearch

Expand Down

0 comments on commit 33acb41

Please sign in to comment.