Requirements

  • PHP >= 5.5.0 (Please read this aritcle for How to Upgrade Your Website PHP Version)
  • cURL is installed and enabled
  • How to check PHP version is running on your website
    • From the Backend of Joomla site
    • Go to System → System Information: this screen contains all system information you may need, the Joomla! Version currently running, and also PHP, database versions and so on.
    • system-infomation.jpg

Configure Amazon ElasticSearch Service

If you already have Elasticsearch service installed on your server or use Elasticsearch from another provider, you can use that one and skip this step. However, you need to manage permission to access your service by yourself.
On this documentation, we will guide you to create Amazon Elasticsearch service and manage its access policy.

Create AWS Account

  • If you already have an AWS account, you can skip this step.
  • When you sign up for Amazon Web Services (AWS), your AWS account is automatically signed up for all services in AWS, including AWS Elasticsearch Service (Amazon ES).
  • To create an AWS Account
  • Open http://aws.amazon.com/, and then choose Create an AWS Account.
  • Follow the instructions to sign up. You need to enter payment information before using Amazon ES. There are no sign-up fees, and charges are not incurred until you create a Elasticsearch domain. You have to pay for the resources that you use only.

Create IAM Account

Services in AWS including  Amazon ES, require you to provide credentials when you access them, so that the service can determine whether you have permissions to access the resources owned by that service. You can create access keys for your AWS account to access the API. However, we don't recommend you to access AWS using the credentials for your AWS account. We recommend that you use AWS Identity and Access Management (IAM) instead.

To create an IAM user.

  • Go to Console Home page
  • Under Security & Identity, choose Identity & Access Management
  • create-iam-user-0.jpg
  • Or you can directly sign in to the Identity & Access Management (IAM) console at https://console.aws.amazon.com/iam/.
  • On navigation pane, choose Users -> Create New Users.
  • create-iam-user-2.jpg
  • In input text 1, type a username and check the checkbox Generate an access key for each user
  • Choose Create
  • Save Access key ID + Access Secret Key to the safe place on your computer, or you can click on Download Credentials button to download csv file.
  • create-iam-user-3.jpg
  • Choose Close to return back to list of users page
  • On  list of users, choose the name (not the checkbox) of the user you  created, you can use Search box to search for username.
  • create-iam-user-4.jpg
  • On user detail page, Save User Amazon Resource Name (User ARN), you also can another Access Key in this page
  • create-iam-user-5.jpg

Create ElasticSearch Domain

  • Go to https://aws.amazon.com
  • Sign in to the console with your AWS account
  • Select Region where you want to create Elasticsearch Service in.
  • You can select region from Dropdown menu item (next to Support menu item) on the top menu
  • select-a-region.jpg 
  • Tips: you should select regions near your customers to reduce data latency of your applications.
  • Under Analytics, choose Elasticsearch Service.
  • choose-elasticsearch-service.jpg

Step 1: Define domain

  • Domain Name: On the Define domain page, for Domain name, type a name for the domain. The name must start with a lowercase letter and must be between 3 and 28 characters. Valid characters are a-z (lowercase only), 0-9, and - (hyphen).
  • Elasticsearch version: For Elasticsearch version, select Version 2.3 or Version 5.1
  • Choose Next

Step 2: Configure Cluster

  • For Instance count, choose 1.
  • For Instance type, choose an instance type for the Amazon ES domain.
  • AWS Free tier

Step 3: Set up Access Policy

  • Select an option Allow or deny access to one or more AWS accounts or IAM users under the Set the domain access policy to dropdown box
  • Enter IAM User ARN what you saved on previous step for the Account ID or ARN field
  • create-elasticsearch-domain-2.jpg
  • Choose OK
  • You will see generated settings for the box Add or edit the access policy. This access policy allows your IAM user to use your Elasticsearch domain resource, that means you can use Access Keys of IAM user to access API to manage Elasticsearch domain (create indices, upload documents, …)
  • create-elasticsearch-domain-3.jpg
  • But in our case, everyone can search data from Elasticsearch domain, so we will edit the access policy to do that. Before editing the access policy, you need to save Elasticsearch ARN in somewhere. Then paste the content below to replace the content in the textbox.
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "[IAM_ARN]"
      },
      "Action": "es:*",
      "Resource": "[ELASTICSEARCH_ARN]"
    },
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "*"
      },
      "Action": "es:ESHttpGet",
      "Resource": "[ELASTICSEARCH_ARN]"
    }
  ]
}
  • Replace the [IAM_ARN] with your IAM user ARN, and replace [ELASTICSEARCH_ARN] with Elasticsearch ARN that you get on the previous step.
  • Choose Create to go to Review page
  • Choose Confirm and create
  • In the Amazon Elasticsearch Service dashboard, Choose the Domain you have just created to open manage domain page where you can get Endpoint URL of your domain.

Avoiding Unexpected Charges

Configure Searchly service

If you are looking for an alternative provider of hosted search solution which is away from AWS, Searchly.com is an option that offer you a good service with a reasonable price.

Create Searchly account

  • Open http://www.searchly.com/
  • Select a plan that suits your needs
  • It has a free "Starter" plan with 2 indices and 5 MB storage (can store about 10K documentations).
  • Sign up and verify your account.

Create Search Space

  • Once your account is verified, you can login its dashboard.
  • You will be redirected to the page where you can create Search Space for the first time login.
  • searchly-1-create-search-space.jpg
  • Type a name for Search Space, select Region, and select version 2.3.x for Elasticsearch version.
  • Choose Create

Create Indices

  • Searchly will grant access to specific indices. Hence, you need to create indices first, then create access key and grant access to them.
  • searchly-1-manage-indices.jpg
  • Select Dashboard > Indices to open the Indices Manager page where you can create an index.
  • Chose New Index
  • On Create New Index form Enter index name
  • searchly-1-create-index.jpg
  • Choose Create button

Create Access Keys and Set up Access Policy

You need to create 2 different Access Keys to index, one is for index request in back-end and one is for search on front-end. Select ACL > Access Keys to open the Access Keys Manager page where you can create an access keys.

searchly-2-manage-access-key.jpg

Create Private Access Key for Index request

  • Choose Create New Access Key
  • searchly-3-create-private-access-key-for-indexing-data.jpg
  • Type Access Key Name
  • Uncheck for Read Only option
  • Select indices that you grant access for.
  • Choose Create

Create Public Access Key for Search request

  • Choose Create New Access Key
  • searchly-4-create-public-access-key-for-searching.jpg
  • Type Access Key Name
  • Check for Read Only option
  • Select indices that you grant access for.
  • Choose Create

Get Connection Urls

  • searchly-5-manage-keys.jpg
  • Click on Details button to open page where you can view details about your Access Key and get Connection Url
  • searchly-5-get-connection-url.jpg

Configure Integration

  • Copy Connection URLs of Private Access Key and Public Access Key and enter them correspondingly to Endpoint and Search Endpoint params on Configuration form of Geek Elasticsearch component.
  • Enter index name what you created to Index param.
  • searchly-6-config-service.jpg
  • Save changes.

Install Component

  • Download install package from our download section here
  • Install it as normally via Joomla installer, it will install Geek Elasticsearch component and its all sub extensions.

Configuration

  • Configure component
  • How to access.
  • Click on Options button at any screen of Geek Elasticsearch admin to access its configuration form.

ElasticSearch Service

  • options-tab-1.jpg
Setting Description

Endpoint

The endpoint for Elasticsearch service

Index

Name of index where your data will be stored in.

NOTE: an index is like a “database” in a relational database, you must use different index for each sites if you have multiple ones.

AWS Region

Select a AWS region where you create an ElasticSearch service in - See Create Elasticsearch Domain section (for AWS ElasticSearch service only).

If you use other-AWS ElasticSearch service, you can ignore this setting.

Username

Enter the username for the user. If you use AWS ElasticSearch service, it can be a username of your AWS account or Access Key Id of IAM user.

Password

Enter the password for the user. If you use AWS ElasticSearch service, it can be a password of your AWS account or Secret Access Key of IAM user.

Send Indirect Request (Send search request through server script) By default, the search module will send direct AJAX request to ElasticSearch service.
But if ElasticSearch service is behind a Firewall and it only allows access from specific IPs, then the direct ajax request from client won't work.
In this case, you need to enable this setting, then the search module will send ajax request to your server, after then the server script will send request to your ElasticSearch service.

Index and search

  • options-tab-2.jpg
Setting Description

Last run index time

The last time when index runs successfully.

Indexer Batchsize

The batch size controls how many items are processed per batch. Large batch sizes require lots of memory whereas small batch sizes require less memory but execute more requests which tends to take longer.

Title Text Weight Multiplier

The multiplier is used to control how much influence matching text has on the overall relevance score of a search result. A multiplier is considered in relationship to the other multipliers. The title text comes from the title of the content.

Body Text Weight Multiplier

The multiplier is used to control how much influence matching text has on the overall relevance score of a search result. A multiplier is considered in relationship to the other multipliers. The body text comes from the summary and/or body of the content.

Path Text Weight Multiplier

The multiplier is used to control how much influence matching text has on the overall relevance score of a search result. A multiplier is considered in relationship to the other multipliers. The path text comes from the SEF URL of the content.

Enable Logging

Enable this option to create a log file in your site's logs folder during the index process. This file is useful for troubleshooting issues with the index process. It is recommended that logging be disabled unless necessary.

Permissions

  • options-tab-3.jpg

Enable indexing plugins

  • The Indexing plugins are which the logic is built to search for items from specific component and return them to Indexer to update the ElasticSearch index. Without these plugins, data from a component cannot be indexed and processed during searching from the Geek ElasticSearch search form.
  • On Dashboard of component, click on Manage button on Indexing Plugins section to open plugin manager pages where you can enable / disable plugins associated with components that you want their data will be indexed in Elasticsearch.
  • manage-indexing-plugins.jpg
  • NOTE: enables only indexing plugins for 3rd components what are installed on your site.

Disable Finder (Smart Search) plugins

  • Because we will use Geek Elasticsearch to replace Joomla Smart Search,  it is no longer need to update Joomla! Smart Search index and you can disable all Finder plugins but Smart Search - Geek ElasticSearch to ignore unnecessary process.
  • disable-finder-plugins.jpg

Trigger Events Plugins

  • These plugins provide functions which are triggered during the content creation process of Joomla! components and immediately update the ElasticSearch index.

Run Indexer

  • Once you completely setup Elasticsearch service and configure component as well as enable indexing plugins, you need to run indexer to index data in Elasticsearch.
  • There are some ways and options to run indexer:

Run full index:

  • Click on Index button on toolbar at any screen of component. It will re-index all content of your site.

Run incremental index:

  • Click on Incremental Index button on toolbar at any screen of component. It will index only new content and update content from Last indexing time run .

Setup cron job:

  • Geek ElasticSearch supports Trigger Events Plugins that help ElasticSearch index up-to-date automatically whenever content items are amended. However, there are some 3rd components not support these Trigger Events plugins to trigger its content creation process or there are some circumstances which you need to re-run the indexer.
  • You can do this manually using Index / Incremental Index toolbar button on the Geek ElasticSearch admin page. You can re-index content automatically by running indexer as a command-line application. This makes it particularly convenient to run the indexer from a cron job.
  • All hostings support to create cron job, but there might be difference of how to create. If you don’t know how to do that, you can ask your hosting provider. The Create a Cron Job form is look like image  below
  • cron-tab-1.jpg
  • You need to specify the time or times when the job is run and the command to run.
  • For the command, you can copy it from Dashboard page on Geek Elasticsearch component admin, it is look like as below
  • /path/to/php -f /home/www/demo/cli/geekelasticsearch_indexer.php
  • Replace the /path/to/php with path to the PHP 5.5.0+ (Because application requires PHP 5.5.0+ to run). Ask your hosting provider for this path if you do not know where this path is.
  • NOTE: crontab will always run incremental index.

Manage indexed content

  • This screen shows a list of all the content items indexed in ElasticSearch.
  • manage-indexed-content.jpg
  • Index - runs the Geek Elasticsearch Indexer. A small popup window will appear with a progress bar which illustrates the indexing process working through the content on your site. Do not close this popup window until the process is finished. On sites which have  large amount of content it may take a long time for the indexing (tens of minutes).
    NOTE: Geek Elasticsearch indexer can be run from the command-line interface (CLI) if required. See
    Setting up cron job section for more detail.
  • Incremental Index - runs the Geek Elasticsearch Indexer, but it only update the index for those content items that have changed since the index was last updated.
  • Publish - makes selected items available to visitors on your website.
  • Unpublish - makes the selected items unavailable to visitors on your website.
  • Delete - deletes the selected content items. Works with one or multiple content items selected. Deleting a content item from Elasticsearch only deletes it from the index and does not affect the content item itself.
  • Clear Index -  you use this feature when you need to completely clear all the existing index entries before completely rebuilding the index.

Create and publish module

  • Go to modules manager page.
  • Create new instance of Module Geek Elasticsearch.
  • Update settings for Search icon, search form and search result to suit your need.
  • Publish and assign module to module position on your template.