ElasticPress.io: First Steps

June 29, 2017 by Thorsten Ott

So you’ve decided to improve your website by using ElasticPress.io, and you’re wondering how to get started. Wonder no more – here are the first steps to start taking advantage of your ElasticPress.io account.

Install ElasticPress WordPress plugin

While you can connect to your ElasticPress.io endpoint with any Elasticsearch client, our ElasticPress plugin is the officially supported integration for our hosted service, and is the best way to integrate WordPress with Elasticsearch.

To install the plugin:

Install the plugin using the Add Plugins screen in the WordPress administrative dashboard, or download a zipped up version via Github and upload it using the Upload Plugin option.
Activate the plugin (network activate for multisite).

Connecting to ElasticPress.io with the ElasticPress plugin

In order to complete this step, you will need your ElasticPress.io credentials and endpoint, which are emailed to you after you setup your account.

Your setup email will contain your Subscription ID, Subscription Username, and ElasticPress.io Host URL. Your Subscription Token can be reset in your ElasticPress.io profile and can only be viewed once for security. These credentials should be entered into the ElasticPress Settings page of the WordPress Dashboard.

NB: If you are a WordPress developer and would prefer to maintain your configuration in wp-config.php, you can always add the following lines instead of completing the Dashboard form:

define( 'EP_INDEX_PREFIX', 'demo-' );
define( 'ES_SHIELD', 'demo:icanhazpassword' );
define( 'EP_HOST', 'https://clusters.elasticpress.io:9999' );

There are a few links at the end of this article explaining how to edit wp-config.php for some popular hosts. Be certain to insert the code before the line that includes wp-settings.php, which looks like this:

require_once ABSPATH . 'wp-settings.php';

Once complete, ElasticPress is ready to go, and you should see an ElasticPress icon in your WordPress administrative dashboard menu.

Indexing your content

With the plugin activated and connected to ElasticPress.io, it is now time to index the data and content stored in WordPress. There are two ways to start an index (or reindex) of your site:

Indexing through the ElasticPress administrative user interface

Indexing using the WordPress dashboard interface is easy: click the “sync” link in the dashboard notification that appears after activating the plugin.

You can reindex at any time by clicking the “circular arrows” icon found in the header of the ElasticPress settings page.

Advanced: indexing with WP-CLI

In some situations, such as a large website with an extremely high volume of content to index, command line indexing is preferred. The ElasticPress plugin includes a WP-CLI command, which uses the WP-CLI interface on the shell of your hosting setup. Note that not all hosting providers offer this option, particularly economy plans.

As the invocation of WP-CLI may vary from provider to provider, we will use the most common, direct access via SSH shell, for this example.

The elasticpress WP-CLI command offers various options which are listed out when calling the command without additional arguments.

$ wp elasticpress

usage: wp elasticpress activate-feature <feature> [--network-wide]
   or: wp elasticpress deactivate-feature <feature> [--network-wide]
   or: wp elasticpress delete-index [--network-wide]
   or: wp elasticpress index [--setup] [--network-wide] [--posts-per-page] [--nobulk] [--offset] [--show-bulk-errors] [--post-type]
   or: wp elasticpress list-features [--all] [--network-wide]
   or: wp elasticpress put-mapping [--network-wide]
   or: wp elasticpress recreate-network-alias
   or: wp elasticpress stats
   or: wp elasticpress status

See 'wp help elasticpress <command>' for more information on a specific command.

To index your site, run the index command.

$ wp elasticpress sync --setup

Indexing posts...

Processed 350/1002 entries. . .
Processed 700/1002 entries. . .
Processed 1002/1002 entries. . .
Number of posts indexed on site 1: 1002
Total time elapsed: 6.289

Success: Done!

To index all of the sites in a network (multisite) implementation, append the –network-wide option to the command above.

Testing and debugging

Once your content is indexed, ElasticPress will seamlessly kick in behind the scenes and intelligently route requests to ElasticPress.io.

Depending on which features you enabled in the settings screen, the plugin will improve everything from the quality of search results to faceted product browsing speed in WooCommerce, and can add related posts or the contents of uploaded documents to search results.

Whether for your own curiosity or for debugging purposes, if you want a glimpse into ElasticPress.io queries you can install the Debug Bar and Debug Bar ElasticPress plugins to see “under the hood” as content is pulled from the ElasticPress index.

We’ve previously covered some debugging tips on our blog.

Where do I go next?

While ElasticPress covers the most common use cases out of the box, unleashing its full potential involves customizing your site build and use case to run sophisticated WP_Query requests through the ElasticPress.io index instead of MySQL. In addition to supercharging the performance of heavy data queries, ElasticPress enables complex queries not supported by WordPress core, for instance cross-site queries on network/multisite installations. More experienced developers can find an introduction to these capabilities on the ElasticPress GitHub page.

The ElasticPress plugin offers a huge variety of filters and actions empowering developers to alter its default behavior and introduce custom weighting schemes or similar alterations. These filters can be discovered by searching through the open source ElasticPress code base.

Finally, you can also use the ep_remote_request() function (added by the ElasticPress plugin) to send raw Elasticsearch queries directly to the ElasticPress.io endpoint. This provides access to most of the features outlined in the Elasticsearch documentation.

Let us help you

ElasticPress.io includes support, so if you’re having trouble following our setup, or an expected feature has gone awry, we’re here to help.

We also have a professional services team who can consult with ElasticPress.io customers, ElasticPress plugin adopters (not hosting with ElasticPress.io), or anyone trying to get the most out of Elastic technologies to:

Entirely handle your setup for you;
Help you customize your build and squeeze the most out of ElasticPress;
Offer training and support for internal teams learning ElasticPress or Elasticsearch.

Just use our contact form and tell us how we can help.