Elastic Indexer

The Elastic Indexer is a command line task runner that synchronizes the Colectica Repository items with an Elasticsearch index.

Prerequisites

The Elastic Indexer requires .NET 8 to be installed.

  1. Download and install the Windows .NET Runtime 8.0.x from https://dotnet.microsoft.com/download/dotnet/8.0

Deploy the Elastic Indexer

  1. First, make sure Colectica Repository and Colectica Portal are installed.

  2. Populate Colectica Repository with metadata.

  3. Download the Elastic Indexer package. This will be named ColecticaElasticIndexer-version.zip and should be included with your Colectica Portal delivery.

  4. Before extracting the Elastic Indexer package, make sure Windows does not have the file blocked. To check this:

    1. In Windows Explorer, right click the Zip file and choose Properties.

    2. Near the bottom of the Properties window, in the Security area, see if there is a checkbox labeled Unblock.

    3. If there is an Unblock checkbox, check the box and click OK.

    4. If there is no such checkbox, proceed to the next step.

  5. Extract the contents of the Elastic Indexer package. In this documentation, the directory to which you extract the file will be referred to as ElasticIndexerDir\.

Configure the Elastic Indexer

  1. Navigate to ElasticIndexerDir\.

  2. If there is not a file named appsettings.json, then copy the appsettings.json.dist file to appsettings.json.

  3. In the appsettings.json file, update the following settings.

    Data - DefaultConnection - ConnectionString

    The full connection string of the database to use to store authentication tables, when using Colectica Portal’s built in user management.

    Data - ColecticaRepository - ConnectionString

    The full connection string of the Colectica Repository database.

    Elasticsearch - Host

    The hostname of the Elasticsearch service.

    Elasticsearch - IndexName

    A prefix for any Elasticsearch indices that will be created

    Note

    The ConnectionString and Elasticsearch settings should match the settings in the Colectica Portal configuration.

Run the Elastic Indexer

  1. Open a command shell and navigate to ElasticIndexerDir\.

  2. Run the following command:

    Colectica.Portal.ElasticIndexer.exe
    

Note

Depending on the size of your data, the Elastic Indexer may take a long time to run during the initial ingest. Subsequence runs will only index new content.

Reoccurring task for the Elastic Indexer

  1. The Elastic Indexer should be run periodically to index new documents using the Windows Task Scheduler. An interval of 5 minutes is recommended for near real time indexing. Also set the Start In directory to the directory containing the elastic indexer executable.

Note

For more information about Windows Task Scheduler, see https://docs.microsoft.com/en-us/windows/win32/taskschd/task-scheduler-start-page

Reindex using the Elastic Indexer

The Elastic Indexer can recreate the Elastic Index and reset the indexed state of the items in the Repository.

  1. Open a command shell and navigate to ElasticIndexerDir\.

  2. Run the following command:

    Colectica.Portal.ElasticIndexer.exe --reindex
    
  3. The Indexer will drop and create a new index, and reset the item indexed states in the Repository.

Custom config files

The Elastic Indexer can run using an alternative configuration file.

  1. Open a command shell and navigate to ElasticIndexerDir\.

  2. Run the following command:

    Colectica.Portal.ElasticIndexer.exe --config myconfig.json
    

Running on alternative versions of Elasticsearch

Colectica currently supports Elasticsearch version 7.x. Historically elasticsearch has not maintained compatible across their major versions.

Starting with Elasticsearch 8.x, the Elasticsearch server provides some backwards compatibility using a version header in its REST api calls.

To try to use a newer version of Elasticsearch with Colectica, you can enable this version header by setting the ElasticIndexer:EnableApiVersioningHeader setting to true in the ElasticIndexer and the Elasticsearch:EnableApiVersioningHeader setting to true in the Colectica Repository.