Using Elasticsearch on Ibexa Cloud

With eZ Platform v3.1 the Enterprise Edition gained support for Elasticsearch. The search engine is an alternative to the Solr search engine supported by eZ Platform since 2015. Both solutions are supported by Ibexa Cloud, our fully integrated managed hosting environment.

eZ Platform Cloud (nowadays known as Ibexa Cloud) is a PaaS (short for Platform as a Service), which means that all the needed server processes are managed automatically for you. You retain full control of your codebase and this includes the configuration for eZ Platform Cloud. This approach is also known as infrastucture as code and it allows easily deploying managed services from a catalogue.

For eZ Platform Cloud the service catalogue has included Elasticsearch for a number of years. With the arrival of eZ Platform v3.1 and support for Elasticsearch, deploying Elasticsearch on eZ Platform Cloud is a matter of configuration. All the needed changes and details are available on eZ Platform Elasticsearch documentation and eZ Platform Cloud Elasticsearch documentation.

Configuring Elasticsearch to run on eZ Platform Cloud

All of the changes needed in deployment are stored in your version control (i.e. git repository). We will need to make modifications to both the service configuration to enable the Elasticsearch service, as well as the application configuration for it to use Elasticsearch as a backend.

It makes sense to first enable the service and make sure we have it up and running before changing the application configuration. Before making any changes create a new environment for developing and testing the configuration before a production deployment. Once done, start by adding the elasticsearch service in .platform/services.yaml configuration file:

elasticsearch:
    type: elasticsearch:7.7
    disk: 512

The above tells eZ Platform Cloud to deploy an instance of the Elasticsearch (version 7.7) with 512 megabytes of disk space. Version and disk space requirements change depending on your eZ Platform version and the size of your application's data. You can change these in the future.

Next we need to make the service accessible to eZ Platform. Edit the .platform.app.yaml file and add a relationship to the elasticsearch service in the relationships configuration block:

relationships:
    database: 'mysqldb:user'
    # ... more services depending on your configuration
    essearch: "elasticsearch:elasticsearch"

With these changes done locally you can push the updates to your remote repository. At the end of the log is a listing of the deployed services. The results should now include elasticsearch:

Redeploying environment master
  # ... more deployment logs

  Opening environment
  Environment configuration
    app (type: php:7.3, size: S, disk: 3072)
    mysqldb (type: mariadb:10.4, size: S, disk: 1024)
    rediscache (type: redis:5.0, size: S)
    elasticsearch (type: elasticsearch:7.7, size: S, disk: 512)
    varnish (type: varnish:6.0, size: S)

With this in place we've now got the service running on eZ Platform Cloud, but it's not being used by eZ Platform yet. This is because we did not make any configuration changes to the application (eZ Platform) yet. For this we will make two changes to the .env file in our project:

# eZ Platform Kernel
SEARCH_ENGINE=elasticsearch

# eZ Platform Elastic Search Engine
ELASTICSEARCH_DSN=http://essearch.internal:9200

The first configuration makes eZ Platform use Elasticsearch as a search backend and the second entry defines the endpoint for the service. When you push your configuration changes to the repository, the build will result in an eZ Platform installation that uses Elasticsearch as a backend.

Finally we need to update the elasticsearch runtime configuration and populate the initial search index. Going forward the updates will be handled by eZ Platform automatically. Open an SSH connection to your environment and execute the configuration and reindex commands:

web@app.0:~$ php bin/console ezplatform:elasticsearch:put-index-template

 [OK] Done.                                                                                                             

web@app.0:~$ php bin/console ezplatform:reindex
Re-indexing started for search engine: eZ Platform Elasticsearch Search Engine
Purging index...
Re-creating index for 17 items across 1 iteration(s), using a single (current) process:
 1/1 [============================] 100% 5 secs/5 secs
Finished re-indexing
web@app.0:~$ 

Once you have verified that your application functions the way it does on this test environment, you can merge the branch with your production one and deploy the changes to production.

NOTE: For development you want to use a local instance of Elasticsearch, so the endpoint should point to a different one. You can override any .env values by adding a unversioned .env.local file and override the configuration options from there: Overriding environment values via .env.local

Conclusion

As you can see from the above, enabling Elasticsearch on eZ Platform is straightforward on a PaaS such as eZ Platform Cloud. The managed nature of the services will make sure the stay up-to-date with the latest patches, and version upgrades are easily managed with environments.

It is also worth noting that the Elasticsearch server is only available from the local environment from within your application instance. This makes it immune to data leak incidents caused by lax configuration practices that expose Elasticsearch servers directly to the public internet.

However if you do want to access the test of production instances' Elasticsearch daemons for analysis or debugging, you can do this securely using an encrypted SSH tunnel. This can be useful if you want to use Kibana to explore and visualize live data from your Elasticsearch index.

Elasticsearch is just one of many improvements we've done to eZ Platform. Read the full details on our most recent release from the blog post: Product Launch: Discover eZ Platform v3.1