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 9, 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
/usr/share/elasticsearch/bin/elasticsearch-plugin install --batch --verbose analysis-icu

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 exec -ti elasticsearch /usr/share/elasticsearch/bin/elasticsearch-plugin install --batch --verbose analysis-icu
docker restart -t 5 elasticsearch

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

Deploying the Augmented Search modules on your server

Deploy the following modules on your Jahia Server, available on the Jahia Store, and directly from the Jahia module administration > Available modules screen:

• 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.
   

Creating the connection between Jahia and Elasticsearch

Since 4.0.0, elasticsearch connection is configured through org.jahia.modules.elasticsearchConnector.cfg OSGi configuration file.

For basic configuration, specify the following properties:

• elasticsearchConnector.host - The IP/hostname of your Elasticsearch server
• elasticsearchConnector.port - The port used by your Elasticsearch server

Secured connection to Elasticsearch cluster

If your Elasticsearch cluster uses security and/or authentication, you can also configure the following additional settings:

• elasticsearchConnector.useXPackSecurity - Enable XPack security integration (authentication)
• elasticsearchConnector.useEncryption - Enable HTTPS encryption for connections
• elasticsearchConnector.user - Username for Elasticsearch authentication
• elasticsearchConnector.password - Encrypted password for Elasticsearch authentication

Use Jahia's encryption utility to generate an encrypted password. One way is to execute this code in tools > groovy console:

org.jahia.utils.EncryptionUtils.passwordBaseEncrypt("myPassword")

Testing the connection

If the connection setup is ok, then you should be able to go to Augmented Search UI (Administration > Configuration > Augmented Search) without any errors displayed. 

It is also possible to test your elasticsearch connection using the graphql query:

query testESConnection {
  admin {
    elasticsearch {
      testConnection
    }
  }
}

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.