Migration Guide - WebDevStudios/wp-search-with-algolia GitHub Wiki

How to promote the plugin from dev to staging and from staging to production.

Introduction

It is a common practice to run your website changes on a development or staging environment before pushing them to production.

The WP Search with Algolia plugin for WordPress requires you to take some additional steps in order to work properly once promoted.

Here are some of the challenges:

Full URLS are indexed

When indexing content, the full URL is always indexed to allow every plugin to be able to intervene in the generation process.

You will always need to re-index all your content from your production environment to update all URLS, otherwise the results will point to your staging environment.

Use index prefixes to allow multiple websites on a single Algolia account

Each index stored in Algolia has a prefix. You should always use a prefix that contains a reference to your current environment's purpose.

For example:

  • mywebsite_prod_ => for production
  • mywebsite_staging_ => for staging
  • mywebsite_dev_ => for development

You should also include a unique way to identify the website, here mywebsite_. By doing so, you ensure that you can easily identify indices even if you have multiple websites bound to a single Algolia account.

Algolia recommends that you use the following pattern for your index prefixes: {websitename}_{environment}_.

Don't forget the trailing underscore if you want your index names to stay readable in the Algolia dashboard.

Avoid breaking frontend search

There are several situations where your frontend implementations might break if you don't take some precautions.

Here are some situations where the frontend might break:

  • If your templates rely on newly indexed fields that have not been pushed yet
  • If you upgrade the plugin and there is a mention of a breaking change on the plugin
  • If you customize the data pushed to Algolia by the means of filter hooks
  • If you install a plugin that uses filter hooks to customize the data pushed to Algolia

To avoid search downtime, it is recommended that you always make sure your website works when disabling the WP Search with Algolia plugin.

You can disable the autocomplete dropdown and the instant search results page experiences without breaking your website.

This is the default behavior if you use the template overriding strategy defined here:

As a best practice, before pushing your implementation to production, it is recommended that you turn off autocomplete and instant search page. You will be able to re-enable them from the production environment once you made sure your indices are up-to-date with the templates.

From staging to production steps

Here are the steps to bring the WP Search with Algolia plugin to production from a staging environment:

  1. Make sure you are using a prefix like mywebsite_staging_, and if not, change it on the Indexing page of the plugin
  2. Disable the autocomplete and instantsearch experiences to make sure your search still works without WP Search with Algolia,
  3. Promote your code and your plugin configuration to production
  4. Update the index name prefix to mywebsite_production_
  5. Click the Re-index everything button on the Indexing page of the plugin
  6. Wait for the indexing to finish
  7. Re-enable the autocomplete and instantsearch features.

You should now have WP Search with Algolia up and running smoothly in your production environment.

Ease environment switching with constants

Starting from version 1.6.0, you can add the following lines to your wp-config.php file:

define( 'ALGOLIA_APPLICATION_ID', '<your_application_id>' );
define( 'ALGOLIA_SEARCH_API_KEY', '<your_search_api_key>' );
define( 'ALGOLIA_API_KEY', '<your_api_key>' );
define( 'ALGOLIA_INDEX_NAME_PREFIX', '<your_index_name_prefix>' );

Adding the constants to your wp-config.php will disable the editing of those fields via the admin panel.

When you are using the constant for setting the indicex name prefix, you should re-index your data form the admin panel.