diff --git a/docs/getting_started/requirements.md b/docs/getting_started/requirements.md index 3a75126f76..8f9a9d8f15 100644 --- a/docs/getting_started/requirements.md +++ b/docs/getting_started/requirements.md @@ -215,7 +215,7 @@ For production setups it's recommended that you use Varnish/Fastly, Redis, NFS/E |Name|Version| |---|---| |Solr|8.11.1+ or 9.8.1+| - |Elasticsearch| 7.16.2+ | + |Elasticsearch| 7.16.2+ or 8.19+ | If you see a "+" next to the product version, it indicates a recommended version or higher within the same major release. For example, "1.18+" means any 1.x version equal to or higher than 1.18, but not 2.x. diff --git a/docs/search/search_engines/elasticsearch/configure_elasticsearch.md b/docs/search/search_engines/elasticsearch/configure_elasticsearch.md index 37df214ff7..29e9f5bd3f 100644 --- a/docs/search/search_engines/elasticsearch/configure_elasticsearch.md +++ b/docs/search/search_engines/elasticsearch/configure_elasticsearch.md @@ -108,40 +108,28 @@ ibexa_elasticsearch: When you configure a cluster-based connection, and the cluster consists of many nodes, you can choose strategies that govern how the cluster reacts to changing operating conditions, or how workload is distributed among the nodes. -#### Connection pool +#### Node pool settings -With this setting you decide how a list of hosts that form a cluster is managed. -The list of active hosts tends to change in time, due to different reasons, such as connectivity issues, host malfunction, or the fact that you add new hosts to the cluster to increase its performance. -By default, the `StaticNoPingConnectionPool` setting is used. +With these settings you decide how nodes in the cluster are selected and how failed nodes are resurrected. +The node pool manages the list of active nodes, which can change over time due to connectivity issues, host malfunction, or when you add new nodes to the cluster to increase performance. -You can change the default setting with the following key: +By default, Elasticsearch uses the `SimpleNodePool` algorithm with `RoundRobin` selector and `NoResurrect` strategy. + +You can customize the node pool behavior with the following settings: ``` yaml : # ... - connection_pool: Elasticsearch\ConnectionPool\ + node_pool_selector: Elastic\Transport\NodePool\Selector\RoundRobin + node_pool_resurrect: Elastic\Transport\NodePool\Resurrect\NoResurrect ``` -For more information and a list of available choices, see [Connection pool](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/connection_pool.html). +For more information and a list of available choices, see [Node pool](https://www.elastic.co/guide/en/elasticsearch/client/php-api/8.19/node_pool.html). !!! tip "Load tests recommendation" - If you change the connection pool setting, it's recommended that you to perform load tests to check whether the change doesn't negatively impact the performance of your environment. - -#### Connection selector - -When the cluster consists of many hosts, the `connection_selector` setting decides what strategy is used to pick a node to send query requests to. -By default, the `RoundRobinSelector` setting is used. - -If you prefer a different strategy, or have created your own, custom strategy, you can change the default setting with the following key: - -``` yaml -: - # ... - connection_selector: Elasticsearch\ConnectionPool\Selectors\ -``` + If you change the node pool settings, it's recommended that you perform load tests to check whether the change doesn't negatively impact the performance of your environment. -For more information and a list of available choices, see [Selectors](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/selectors.html). ##### Number of retries @@ -154,9 +142,9 @@ By default, `null` is used, which means that the number of retries equals to the retries: null ``` -Depending on the connection pool that you select, [[= product_name =]]'s reaction to reaching the maximum number of retries might differ. +Depending on the node pool settings that you select, [[= product_name =]]'s reaction to reaching the maximum number of retries might differ. -For more information, see [Set retries](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/set-retries.html). +For more information, see [Set retries](https://www.elastic.co/guide/en/elasticsearch/client/php-api/8.19/set-retries.html). ## Configure Elasticsearch Cloud @@ -216,10 +204,10 @@ ibexa_elasticsearch: ### API key authentication If your Elasticsearch cluster is protected by API keys, you must provide the key and secret in authentication configuration to connect [[= product_name =]] with the cluster. -With API key authentication you can define different authorization levels, such as [`create_index` or `index`](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/security-privileges.html#privileges-list-indices). +With API key authentication you can define different authorization levels, such as [`create_index` or `index`](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/security-privileges.html#privileges-list-indices). Such approach proves useful if the cluster is available to the public. -For more information, see [Create API key](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/security-api-create-api-key.html). +For more information, see [Create API key](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/security-api-create-api-key.html). When using API key authentication, you must pass the following parameters to authenticate access to the cluster: @@ -228,7 +216,7 @@ When using API key authentication, you must pass the following parameters to aut # ... authentication: type: api_key - credentials: ['', ''] + credentials: ['', ''] ``` For example: @@ -241,9 +229,34 @@ ibexa_elasticsearch: elastic_cloud_id: 'test:ZWFzdHVzMi5henVyZS5lbGFzdGljLWNsb3VkLmNvbTo5MjQzJGUwZ' authentication: type: api_key - credentials: ['8Ek5f3IBGQlWj6v4M7zG', 'rmI6IechSnSJymWJ4LZqUw'] + credentials: ['ui2lp2axTNmsyakw9tvNnw', 'VuaCfGcBCdbkQm-e5aOx'] ``` +Alternatively, pass the encoded API key value, which Elasticsearch also calls "API key credentials": + +``` yaml +: + # ... + authentication: + type: api_key + credentials: [''] +``` + +For example: + +``` yaml +ibexa_elasticsearch: + connections: + cloud: + debug: true + elastic_cloud_id: 'test:ZWFzdHVzMi5henVyZS5lbGFzdGljLWNsb3VkLmNvbTo5MjQzJGUwZ' + authentication: + type: api_key + credentials: ['VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=='] +``` + +Refer to the [examples in Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/security-api-create-api-key.html#security-api-create-api-key-example) to see the difference between API key, API key id, and encoded API key. + ### SSL When you need to protect your communication with the Elasticsearch server, you can use SSL encryption. @@ -292,24 +305,27 @@ To do this, pass the following setting under the `ssl` key: verification: false ``` -For more information, see [Elasticsearch: SSL Encryption](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/connceting.html#ssl-encryption). +For more information, see [Elasticsearch: SSL Encryption](https://www.elastic.co/guide/en/elasticsearch/client/php-api/8.19/connecting.html#ssl-encryption). ### Enable debugging In a staging environment, you can log messages about the status of communication with Elasticsearch. You can then use Symfony Profiler to review the logs. -By default, debugging is disabled. To enable debugging, you can toggle either of the following two settings: +By default, debugging is disabled. To enable debugging, you can use the following setting: ``` yaml : # ... debug: - trace: ``` -- `debug` logs basic information about a request, such as request status and time. -- `trace` logs additional information, such as steps to reproduce an exact copy of a query. +- `debug` logs information about requests, including request status and timing + +!!! note "Elasticsearch 7 compatibility" + + If you're using Elasticsearch 7, you can also use the `trace` setting for additional debugging information. + This setting is deprecated and removed in Elasticsearch 8. !!! tip @@ -370,7 +386,7 @@ Index names use the following pattern: - `settings` - Settings under this key control all aspects related to an index. -For more information and a list of available settings, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/index-modules.html#index-modules-settings). +For more information and a list of available settings, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/index-modules.html#index-modules-settings). For example, you can define settings that convert text into a format that is optimized for search, like a normalizer that changes a case of all phrases in the index: @@ -392,7 +408,7 @@ For more information and a list of available settings, see [Elasticsearch docume - `mappings` - Settings under this key define mapping for fields in the index. -For more information about mappings, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/mapping.html). +For more information about mappings, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/mapping.html). When you create a custom index template, with settings for your own field and document types, make sure that it contains mappings for all searchable fields that are available in [[= product_name =]]. For an example of default configuration with a list of searchable fields. @@ -401,7 +417,7 @@ For more information about mappings, see [Elasticsearch documentation](https://w ### Fine-tune the search results Your search results can be adjusted by configuring additional parameters. -For a list of available mapping parameters and their usage, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/mapping-params.html). +For a list of available mapping parameters and their usage, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/mapping-params.html). For example, you can apply a mapping parameter, in this case, a normalizer, to a specific mapping under the `dynamic_templates` key: @@ -487,9 +503,9 @@ For more information about specifying the pattern for your language, see [Define #### Create config for language specific analyzer -For information about configuring an analyzer for each specific language, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/analysis-lang-analyzer.html). +For information about configuring an analyzer for each specific language, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/analysis-lang-analyzer.html). -An adoption of the [English analyzer](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/analysis-lang-analyzer.html#english-analyzer) in [[= product_name =]] configuration looks like this: +An adoption of the [English analyzer](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/analysis-lang-analyzer.html#english-analyzer) in [[= product_name =]] configuration looks like this: ```yaml hl_lines="3-5 15-23 35 41-52 94 99" [[= include_file('code_samples/search/custom/config/packages/elasticsearch-en.yaml') =]] @@ -519,7 +535,7 @@ ibexa_elasticsearch: - ger_de ``` -For more information about how Elasticsearch handles settings and mappings from multiple templates that match the same index, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/indices-templates-v1.html#multiple-templates-v1). +For more information about how Elasticsearch handles settings and mappings from multiple templates that match the same index, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/index-templates.html). # Extend Elasticsearch diff --git a/docs/search/search_engines/elasticsearch/elasticsearch_overview.md b/docs/search/search_engines/elasticsearch/elasticsearch_overview.md index 151fb797c3..c84ba47a66 100644 --- a/docs/search/search_engines/elasticsearch/elasticsearch_overview.md +++ b/docs/search/search_engines/elasticsearch/elasticsearch_overview.md @@ -14,7 +14,7 @@ Instead of searching text directly, it searches and index. Thanks to this mechanism, it's able to achieve fast response. For a detailed description of advanced settings that you might require in a specific production environment, see the documentation provided by Elastic. -Start with the [Set up Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.7/setup.html) section. +Start with the [Set up Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/setup.html) section. **Prerequisite** @@ -36,4 +36,4 @@ To update the schema and then reindex the search, use the following commands: ```bash php bin/console ibexa:elasticsearch:put-index-template --overwrite php bin/console ibexa:reindex -``` \ No newline at end of file +``` diff --git a/docs/search/search_engines/elasticsearch/install_elasticsearch.md b/docs/search/search_engines/elasticsearch/install_elasticsearch.md index bcfeeafee1..495337dadc 100644 --- a/docs/search/search_engines/elasticsearch/install_elasticsearch.md +++ b/docs/search/search_engines/elasticsearch/install_elasticsearch.md @@ -6,16 +6,16 @@ description: Install Elasticsearch to use it with Ibexa DXP. ## Download and install Elasticsearch -[Install Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.7/install-elasticsearch.html) on your server. +[Install Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/install-elasticsearch.html) on your server. As an example, use the following [Docker](https://docs.docker.com/get-started/docker-overview/) command: ```yml -docker run -d --name ibexa-dxp-elasticsearch -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:7.16.2 +docker run -d --name ibexa-dxp-elasticsearch -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:8.19.0 ``` !!! note - [[= product_name =]] supports Elasticsearch in version 7.16.2 or higher. + [[= product_name =]] supports Elasticsearch in versions 7.16 and 8.19. ## Verify the instance @@ -26,21 +26,21 @@ It should be similar to the following example: ``` json { - "name" : "doej-MacPro-mTkBe", - "cluster_name" : "elasticsearch", - "cluster_uuid" : "WLYqnQ_lSZGbX-vDIe_vZQ", - "version" : { - "number" : "7.7.0", - "build_flavor" : "default", - "build_type" : "tar", - "build_hash" : "5b1fea5", - "build_date" : "2020-05-10T02:35:59.208Z", - "build_snapshot" : false, - "lucene_version" : "8.5.1", - "minimum_wire_compatibility_version" : "6.8.0", - "minimum_index_compatibility_version" : "6.0.0-beta1" - }, - "tagline" : "You Know, for Search" + "name" : "f45b86ab3726", + "cluster_name" : "docker-cluster", + "cluster_uuid" : "5OAEghGPTLSd4jUJColoNQ", + "version" : { + "number" : "8.19.0", + "build_flavor" : "default", + "build_type" : "docker", + "build_hash" : "93788a8c2882eb5b606510680fac214cff1c7a22", + "build_date" : "2025-07-23T22:10:18.138212839Z", + "build_snapshot" : false, + "lucene_version" : "9.12.2", + "minimum_wire_compatibility_version" : "7.17.0", + "minimum_index_compatibility_version" : "7.0.0" + }, + "tagline" : "You Know, for Search" } ``` @@ -91,4 +91,4 @@ php bin/console ibexa:reindex !!! caution "Risks of premature indexing" Don't reindex your data before you create index templates. - Otherwise Elasticsearch attempts to use its [dynamic field mapping](https://www.elastic.co/guide/en/elasticsearch/reference/7.7/dynamic-field-mapping.html) feature to create type mappings automatically. + Otherwise Elasticsearch attempts to use its [dynamic field mapping](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/dynamic-field-mapping.html) feature to create type mappings automatically. diff --git a/docs/update_and_migration/from_5.0/update_from_5.0.md b/docs/update_and_migration/from_5.0/update_from_5.0.md index 2b63094d43..3ab34d8595 100644 --- a/docs/update_and_migration/from_5.0/update_from_5.0.md +++ b/docs/update_and_migration/from_5.0/update_from_5.0.md @@ -182,6 +182,88 @@ If the platform comes from lower than v5.0.3 and is updated to higher than v5.0. ## v5.0.5 +### Elasticsearch 8 support + +As of v5.0.5, [[= product_name =]] adds support for Elasticsearch 8.19 or higher. +You can continue using [unsupported Elasticsearch 7.16.2+](https://www.elastic.co/support/eol), but it's recommended to upgrade to Elasticsearch 8 for improved performance and security features. + +When choosing to keep using Elasticsearch 7.16.2, adjust your configuration as described in the [Update configuration](#update-configuration) section below to avoid using deprecated settings. + +If you choose to upgrade to Elasticsearch 8, follow these steps: + +#### Update Elasticsearch server + +Upgrade your Elasticsearch server to version 8.19 or higher. +Follow the [Elasticsearch upgrade guide](https://www.elastic.co/guide/en/elastic-stack/8.19/upgrading-elastic-stack.html#prepare-to-upgrade) for detailed instructions. + +When using [[= product_name_cloud =]], see [Elasticsearch service](https://docs.upsun.com/add-services/elasticsearch.html) for a list of supported versions. + +#### Update configuration + +Update your configuration in `config/packages/ibexa_elasticsearch.yaml`. + +##### Replace deprecated connection pool settings + +The deprecated `connection_pool` and `connection_selector` settings are now ignored and don't have any effect. +Replace them with appropriate `node_pool_selector` and `node_pool_resurrect` settings: + +``` yaml +# Old configuration (Elasticsearch 7 - deprecated) +ibexa_elasticsearch: + connections: + default: + connection_pool: 'Elasticsearch\ConnectionPool\StaticNoPingConnectionPool' + connection_selector: 'Elasticsearch\ConnectionPool\Selectors\RoundRobinSelector' +``` + +``` yaml +# New configuration (Elasticsearch 8) +ibexa_elasticsearch: + connections: + default: + node_pool_selector: 'Elastic\Transport\NodePool\Selector\RoundRobin' + node_pool_resurrect: 'Elastic\Transport\NodePool\Resurrect\NoResurrect' +``` + +For more information, see [Node pool settings](configure_elasticsearch.md#node-pool-settings). + +##### Remove trace option + +The `trace` debugging option is no longer available. + +``` yaml +# Old configuration (Elasticsearch 7) +ibexa_elasticsearch: + connections: + default: + debug: true + trace: true +``` + +``` yaml +# New configuration (Elasticsearch 8) +ibexa_elasticsearch: + connections: + default: + debug: true + # Trace option is no longer available +``` + +#### Reindex content + +After upgrading to Elasticsearch 8 and updating your configuration, reindex the search engine: + +1. Push the index templates: + + ``` bash + php bin/console ibexa:elasticsearch:put-index-template --overwrite + ``` + +2. Reindex your content: + + ``` bash + php bin/console ibexa:reindex + ### Database update Run the provided SQL upgrade script to ensure the Messenger tables for [background tasks](background_tasks.md) exist in your database: