ModuleInstall
-
⚠️ This documentation is suitable for ElasticSuite >= 2.5.0. If using an older version please refer to this documentation. -
⚠️ ElasticSearch supported version :- ElasticSearch 7.x is supported.
- ElasticSearch 6.x is supported.
- ElasticSearch 5.x is supported.
- ElasticSearch 2.x support is deprecated and have been removed since ElasticSuite 2.6.0.
-
ElasticSearch 5.x / 6.x / 7.x with :
- ICU (analysis-icu) and Phonetic (analysis-phonetic) plugin installed
-
Depending the version of ElasticSuite :
| Magento Version | ElasticSuite Latest Version | Supported Elasticsearch Version |
|---|---|---|
| Magento 2.0.x Opensource (CE) / Commerce (EE) | ElasticSuite 2.1.x : composer require smile/elasticsuite ~2.1.0
|
2.x |
| Magento 2.1.x Opensource (CE) / Commerce (EE) | ElasticSuite 2.3.x : composer require smile/elasticsuite ~2.3.0
|
2.x & 5.x |
| Magento 2.2.x Opensource (CE) / Commerce (EE) | ElasticSuite 2.6.x : composer require smile/elasticsuite ~2.6.0
|
5.x & 6.x |
| Magento <2.3.5 Opensource (CE) / Commerce (EE) | ElasticSuite 2.8.x : composer require smile/elasticsuite ~2.8.0
|
5.x & 6.x |
| Magento >=2.3.5 Opensource (CE) / Commerce (EE) | ElasticSuite 2.9.x : composer require smile/elasticsuite ~2.9.0
|
6.x & 7.x |
| Magento 2.4.0 Opensource (CE) / Commerce (EE) | ElasticSuite 2.10.1 : composer require smile/elasticsuite 2.10.1
|
6.x & 7.x |
| Magento >=2.4.1 Opensource (CE) / Commerce (EE) | ElasticSuite 2.10.x : composer require smile/elasticsuite ~2.10.0
|
6.x & 7.x |
In order to get a properly set up ElasticSearch server you should read the following page of the wiki ElasticSearch server configuration
composer require smile/elasticsuiteStarting from 2.10.6 version we support using the legacy Magento parameters for Elasticsearch when installing the application.
| Name | Value | Required? |
|---|---|---|
--search-engine |
Set this to elasticsuite
|
Yes |
--elasticsearch-host |
The host name or IP address where Elasticsearch is running. The default is localhost. |
Yes |
--elasticsearch-port |
The port for incoming HTTP requests. The default is 9200. |
Yes |
--elasticsearch-index-prefix |
A prefix that identifies the Elasticsearch index. The default is magento2. |
No |
--elasticsearch-timeout |
The number of seconds before the system times out. The default is 15. |
No |
--elasticsearch-enable-auth |
Enables authentication on the Elasticsearch server. The default is false. |
No |
--elasticsearch-username |
The user ID to authenticate Elasticsearch | No, unless authentication is enabled |
--elasticsearch-password |
The password to authenticate Elasticsearch | No, unless authentication is enabled |
This will you get all set as Elasticsuite will fetch his configuration from the legacy Magento parameter.
You can have an example of how we install in our Github Actions
The command should be something like this :
bin/magento setup:install --base-url=https://magento2.test \
--db-host=database --db-name=magento2 --db-user=magento2 --db-password=magento2 \
--admin-firstname=Magento --admin-lastname=User [email protected] \
--admin-user=admin --admin-password=admin123 --language=en_US \
--currency=USD --timezone=America/Chicago \
--search-engine=elasticsuite
--elasticsearch-host=elasticsearch \
--elasticsearch-port=9200 \
--cleanup-database
If you have a multi-node Elasticsearch cluster, it's a good practice to give all the client nodes FQDN to the Elasticsearch connector, as it will be able to benefit of round-robin when querying the server.
Magento legacy parameters does not allow this, in this case, you can use the Elasticsuite specific parameter --es-hosts to take care of it, in addition to the other parameters.
Like this :
bin/magento setup:install --base-url=https://magento2.test \
--db-host=database --db-name=magento2 --db-user=magento2 --db-password=magento2 \
--admin-firstname=Magento --admin-lastname=User [email protected] \
--admin-user=admin --admin-password=admin123 --language=en_US \
--currency=USD --timezone=America/Chicago \
--search-engine=elasticsuite
--elasticsearch-host=elasticsearch \
--elasticsearch-port=9200 \
--es-hosts="node1.fqdn:9200,node2.fqdn:9200,node3.fqdn:9200" \
--cleanup-database
You can configure ElasticSuite during Magento initial setup by using the following parameters in the setup:install command :
| Param | Description | Example value |
|---|---|---|
--es-hosts |
This a comma-separated list of servers in the [host]:[port] format | es-node1:9200,es-node2:9200 |
--es-enable-ssl |
Use this flag if you want to access to your Elasticsearch server through https. | 0 or 1 |
--es-user |
The user you want to use to connect ES (can be empty) | username |
--es-pass |
The password you want to use to connect ES (can be empty) | password |
Example :
bin/magento setup:install <your params> --es-hosts="elasticsearch:9200" --es-user="username" --es-pass="changeme"
bin/magento setup:install --base-url=https://magento2.test \
--db-host=database --db-name=magento2 --db-user=magento2 --db-password=magento2 \
--admin-firstname=Magento --admin-lastname=User [email protected] \
--admin-user=admin --admin-password=admin123 --language=en_US \
--currency=USD --timezone=America/Chicago \
--search-engine=elasticsearch7
--elasticsearch-host=elasticsearch \
--elasticsearch-port=9200 \
--es-hosts="elasticsearch:9200" \
--cleanup-database
If your Magento instance is already installed, you have to enable the ElasticSuite modules using :
bin/magento module:enable Smile_ElasticsuiteCore Smile_ElasticsuiteCatalog Smile_ElasticsuiteSwatches Smile_ElasticsuiteCatalogRule Smile_ElasticsuiteVirtualCategory Smile_ElasticsuiteThesaurus Smile_ElasticsuiteCatalogOptimizer Smile_ElasticsuiteTracker Smile_ElasticsuiteAnalytics Smile_ElasticsuiteAdminNotification
Then configure the ElasticSearch server to point to your ElasticSearch cluster (optional if using default server location, http://localhost:9200) and reimport the config :
bin/magento config:set -le smile_elasticsuite_core_base_settings/es_client/servers node-1:9200,node-2:9200
bin/magento config:set -le smile_elasticsuite_core_base_settings/es_client/enable_https_mode 0
bin/magento config:set -le smile_elasticsuite_core_base_settings/es_client/enable_http_auth 0
bin/magento config:set -le smile_elasticsuite_core_base_settings/es_client/http_auth_user ""
bin/magento config:set -le smile_elasticsuite_core_base_settings/es_client/http_auth_pwd ""
bin/magento config:set -le catalog/search/engine elasticsuite
bin/magento app:config:import
Following configuration are available :
| Config path | Description |
|---|---|
| smile_elasticsuite_core_base_settings/es_client/servers | This a comma-separated list of servers in the [host]:[port] format |
| smile_elasticsuite_core_base_settings/es_client/enable_https_mode | Enable this parameter if you want to access to your Elasticsearch server through https. |
| smile_elasticsuite_core_base_settings/es_client/enable_http_auth | Enable this one if your Elasticsearch server uses basic HTTP authentication |
| smile_elasticsuite_core_base_settings/es_client/http_auth_user | If you are using HTTP authentication, set your user auth |
| smile_elasticsuite_core_base_settings/es_client/http_auth_pwd | If you are using HTTP authentication, set your user password |
Then upgrade your Magento setup using :
bin/magento setup:upgrade
You can configure your ElasticSearch server via Stores > Configuration > Smile Elastic Suite > Base Settings
| Parameter | Default value | Description |
|---|---|---|
| ElasticSearch servers list | localhost:9200 | This a comma-separated list of servers in the [host]:[port] format where you should indicate all your ElasticSearch nodes. E.g. : "es-node1.fqdn:9200, es-node2.fqdn:9200". |
| Use HTTPS | No | Enable this parameter if you want to access to your Elasticsearch server through https. |
| Enable basic HTTP authentication | No | Enable this one if your Elasticsearch server uses basic HTTP authentication |
| Basic HTTP authentication user | empty | If you are using HTTP authentication, set your user auth in this field. |
| Basic HTTP authentication password | empty | If you are using HTTP authentication, set your user password in this field. |
| Enable debug mode | No | When this parameter is set to "Yes", the module produces logs through the Magento logging system. |
| Server connection timeout | 1 | In seconds, the default timeout used when querying the server. |
Note : Some field may be disabled if you have used the recommended install methods listed bellows. This prevent user to change the client configuration related to their environment by mistake.
| Parameter | Default value | Description |
|---|---|---|
| Indices alias name | magento2 | The default alias put by the module on Magento's related indices. An alias per store and entity type will be generated with the following format : [indices_alias_name]_[store_code]_[entity_type]. E.g. : magento2_default_catalog_product. |
| Indices name pattern | {{YYYYMMdd}}_{{HHmmss}} | The horodated pattern used when creating new index. An index name per store and entity type, based on the horodated pattern, will be generated with the following format : [indices_alias_name]_[store_code]_[entity_type]_[horodated_pattern]. The E.g. : magento2_default_catalog_product_20160304_094708. |
| Number of shards per index | 1 | The number of shards per index. A shard is a single Lucene instance and they are distributed by ElasticSearch amongst all nodes in the cluster. You can see the Shard definition on the ElasticSearch glossary for more informations. |
| Number of replicas per index | 0 | The number of replicas shards per index. Main purposes of replica shards is for failover : if the node holding a primary shard dies, a replica is promoted to the role of primary. You can read more about Replica Shards on the ElasticSearch documentation. |
First, the number of shards : you can read the Elasticsearch documentation about sizing.
The phrase that is important to keep in mind is : Searching fifty 1GB shards will take substantially more resources than searching a single 50GB shard containing the same data..
So it's highly likely that you need only 1 shard, except if you have a very big catalog. You should begin with 1 shard.
And then, check the size of your indices after a first fulltext reindex. You can check indices sizes through the Elasticsuite > Indices menu.
If your index is more than several Gigabytes, you could begin considering to split this into two shards.
What you must also have in mind is the fact that, for each Elasticsearch node, the allowed heap should cover your shard size.
The number of shards is not linked to your number of Elasticsearch nodes : if you have 1 shard and several nodes, you'll have this shard replicated on other nodes by the replication mechanism. Replicas are used for reading, so this will allow each node to be used for searching.
The number of replicas should be, in most cases, equivalent to "number of 'data' nodes -1".
For the vast majority of Elasticsearch cluster architectures, you have 3 nodes that have the 'data' role, meaning you'll want to use 2 replicas.
If you are building a more complex cluster, with "client only" roles for some nodes, you'll just want to consider the number of "data" nodes for calculating your number of replicas.
- except if your index is very big : go for 1 shard
- number of replicas should be : your number of nodes -1
So, in most cases, in production you have 3 Elasticsearch nodes, go for :
- 1 shard
- 2 replicas
You can configure Magento to use Smile ElasticSuite as search engine via Stores > Configuration > Catalog > Catalog Search
| Parameter | Default value | Description |
|---|---|---|
| Minimal Query Length | 1 | The minimal search query length to be processed by the engine. |
| Maximum Query Length | 128 | The maximum search query length to be processed by the engine. |
| Search Engine | Smile ElasticSuite | The default Search Engine used by Magento. |
Once you have completed all previous points, you can process a full reindexing of the catalogsearch_fulltext index.
bin/magento index:reindex catalogsearch_fulltext
bin/magento index:reindex elasticsuite_categories_fulltext
bin/magento index:reindex elasticsuite_thesaurusOnce the reindex is done, you are all set and can view your frontend catalog and search pages being rendered via Smile Elastic Suite !