Installing Augmented Search on-premises

Getting the proper license

Augmented Search is not included in the jContent/jEnterprise subscriptions, thus a dedicated license is required to use it. Contact your account manager, or the Jahia support, to get an Augmented Search license.

Installing Elasticsearch

The first step is to install the latest version of Elasticsearch 7, or to use an Elastic Cloud environment.

 If your Elasticsearch cluster is using X-Pack, please consult our dedicated page related to X-Pack configuration.

Support for additional languages

Some deployments may require support for less common languages (or to be more specific, analyzers and tokenizers not provided by default with Elasticsearch). 

You can find more details about analysis plugin in Elasticsearch's documentation.

Configuring Elasticsearch

You can easily add the necessary plugin by executing the following command on each node of your Elasticsearch cluster:

/usr/share/elasticsearch/bin/elasticsearch-plugin install --batch --verbose analysis-stempel
/usr/share/elasticsearch/bin/elasticsearch-plugin install --batch --verbose analysis-kuromoji

Then restart your Elasticsearch node.

With Docker

If you're running Elasticsearch in Docker, this can be done easily with this command:

docker exec -ti elasticsearch /usr/share/elasticsearch/bin/elasticsearch-plugin install --batch --verbose analysis-stempel
docker exec -ti elasticsearch /usr/share/elasticsearch/bin/elasticsearch-plugin install --batch --verbose analysis-kuromoji
docker restart -t 5 elasticsearch

Assuming "elasticsearch" is the name of your running Elasticsearch container.

Deploying the Augmented Search module package on your server

Deploy the Augmented Search Enterprise Distribution package on your Jahia Server. It’s available on the Jahia Store, and directly from the Jahia module administration > Available modules screen.

This package includes the following modules:

• Database Connector
• Elasticsearch Connector
• Augmented Search
  This module provides the indexation logic and the GraphQL API endpoint to run search queries
• Augmented Search UI
  This module is a sample search implementation, providing a UI component ready to be used inside Jahia pages to display a search UI.

Note: these modules can be retrieved, or updated, individually from the Jahia Store.
 

Creating the connection between Jahia and Elasticsearch

In the Jahia administration UI, go into Administration>Configuration>Database Connector, and create a new connection by clicking New connection.

Select the elastic database type and create a new Elasticsearch connection by filling the following settings:

• Host
  The IP/hostname of your Elasticsearch server
• Port
  The port used by your Elasticsearch server
• Id
  The name of the Elasticsearch connection you are creating, this unique ID is then used by Augmented Search to identify the Elasticsearch cluster to use.

Secured connection to Elasticsearch cluster

If your Elasticsearch cluster uses security:

1. go to the Advanced tab
2. Check the Use Security box
3. If needed, switch to HTTPS by enabling the Encryption toggle
4. Type the username and password
5. Click Test to verfify the settings
6. Click Create

Select the Elasticsearch database connection for Augmented Search

In the Jahia administration UI, go into Administration>Configuration>Augmented Search and select the database connection you want to use.

If plugins are installed on your Elasticsearch cluster (such as stemmers for additional languages) those would be displayed here.

Note that although it is possible to change the database connection, all sites will need to be re-indexed. 
 

Enabling Augmented Search on your sites and first indexation

Augmented Search is not enabled on existing sites by default, and needs to be enabled on each site individually.

To enable Augmented Search on a site:

• Navigate to Administration > Configuration > Augmented Search
  If the Augmented Search entry is not displayed after the deployment of the Augmented Search package, then you probably simply need to refresh the page in your browser
• In Sites indexation, click Add Site
• After adding a site, click Start Indexing beside the site to trigger indexing for the site. You can click on the button on the top-right corner to trigger indexing for all sites at once.

Indexing will start right after clicking on the button and results will progressively become available for search. Indexation times vary as they depend on the size of the site and to your server sizing.

New contents, and content updates, will now be automatically indexed.

Verification

At that point and before continuing further, it's a good idea to run a simple search query via the GraphQL playground (in Tools > GraphQL) to validate the availability of data.

query {
  search (q: "jahia"){
    results {
    totalHits
      hits {
        displayableName
      }
    }
  }
}

You can begin by modifying the above query to your liking, replacing "jahia" with any other search term relevant to your site(s). You can also pass a siteKeys parameter to the search node to restrict the search to a single site:

query {
  search 
  (
    q: "jahia"
    siteKeys: ["mySite"]
  )
  {
    results {
      totalHits
      hits {
        displayableName
      }
    }
  }
}

Adding the demo search component to your site

The Augmented Search UI module provides a demo search form component. To use it in your site:

• Enable the Augmented Search UI module on your site
• In Page Composer, create a new “Augmented Search” page
• In the Page, add the Search and Queries > Augmented Search component 
• Publish the page

In live, on your page, you can now run search queries with Augmented Search, and use the predefined Categories, tags and last modification date facets.