## Configure the Index used by Geoportal Server

This page describes how to configure the search index of choice for use by Geoportal Server. 

Geoportal Server currently supports both [Elastic](https://www.elastic.co/) and [OpenSearch](https://opensearch.org/) indexes. Both can be run locally on a virtual machine, in a container, or used as a cloud Platform-As-A-Service (PAAS) service offered by the major cloud providers.

OpenSearch is a fork from Elasticsearch with API compatibility (for now) but different licensing models. We leave the choice for index technology up to the implementer of Geoportal Server and will continue to aim to support both.

### Index related parameters within Geoportal

This section describes index related parameters within geoportal, the parameters are located in [Tomcat9]/webapps/geoportal/WEB-INF/classes/config/app-context.xml


```
         <beans:bean id="elasticContext" class="com.esri.geoportal.lib.elastic.ElasticContextHttp">
		<beans:property name="clusterName" value="${es_cluster:elasticsearch}" />
		<beans:property name="indexName" value="${gpt_indexName:metadata}" />
		<beans:property name="collectionIndexName" value="${gpt_collectionIndexName:collections}" />
		<beans:property name="indexNameIsAlias" value="true" />
		<beans:property name="autoCreateIndex" value="true" />
		<beans:property name="allowFileId" value="false" />
		<beans:property name="mappingsFile" value="${gpt_mappingsFile:config/elastic-mappings.json}" />
		<beans:property name="mappingsFile7" value="${gpt_mappingsFile:config/elastic-mappings-7.json}" />
		<beans:property name="httpPort" value="9200" />		
		<beans:property name="proxyBufferSize" value="8192" />
		
		<!-- Uncomment and complete the following if you want to use secured Elastic -->
		<!--
		<beans:property name="useHttps" value="true" />
		<beans:property name="username" value="" />
		<beans:property name="password" value="" />	-->	
 
		<beans:property name="nodes">
			<!-- The list of host names within the Elasticsearch cluster, one value element per host -->
			<beans:list>
				<beans:value>${es_node:localhost}</beans:value>
			</beans:list>
		</beans:property>
	</beans:bean>
```

Parameter Name | Description
-------------- | ------------
clusterName | The name of the cluster, default value is "elasticsearch", you can specify the name here directly, or you can have a system property named "es_cluster" that defines the cluster name.
indexName | The name of the index in the search engine context. **Note**: the index name cannot be 'items'!
collectionIndexName | The name of the index that stores Collection metadata. **Note**: the collections index name cannot be 'items'!
indexNameIsAlias | If indexName is an alias for the index name. When Geoportal starts for the first time, it will create an index named "metadata_v1" and aliased as "metadata" by default. If for some reason you want to start with a new empty index, change the `indexName` is sufficient.
autoCreateIndex | If set to "true", index will be created when Geoportal starts and finds the index does not exist.
allowFileId | If set to "true", you can use the metadata file id as the id in the index, the id will not be used if the id contains forward slash (e.g. in urls).
mappingsFile | The location of Geoportal mapping defines field mappings for the search engine.
nodes |this contain the nodes for search index cluster, default is localhost.

### Configure Geoportal to use Elasticsearch with multiple nodes 
Geoportal supports use with a multi-node search index cluster. If you have a cluster with multiple nodes, you can define it in one of two ways:

 * Add the following to [Tomcat8]/conf/catalina.properties, es_node is a comma separated list of host names.
   
```
#Geoportal
es_cluster=myclustername
es_node=host1,host2
```

 * OR, update app-context.xml
   
```
  <beans:bean id="elasticContext" class="com.esri.geoportal.db.elastic.ElasticContext">
    <beans:property name="clusterName" value="myclustername" />
    <beans:property name="nodes">
        <beans:value>host1</beans:value>
        <beans:value>host2</beans:value>
      </beans:list>
    </beans:property>
  </beans:bean>  
```

For further information on setting up and configuring a multi-node search cluster, we defer to the documentation of the search engine of choice. 

### Disable SSL in Elasticsearch

Elastic 8.x is by default SSL enabled. To disable SSL in Elastic 8.x, please follow below steps:

```
Open <elastic_root>\config\elasticsearch.yml and find the following lines. change 'true' to false

xpack.security.transport.ssl.enabled: true
xpack.security.http.ssl.enabled: true

Save the file and restart elasticsearch
```

### Configure Geoportal to use local secured index
```
Open app-context.xml

<beans:property name="httpPort" value="9200" />
<beans:property name="username" value="index username" />
<beans:property name="password" value="index password" />
<beans:property name="useHttps" value="true" />

```

### Configure Geoportal to use a cloud-hosted index

It is possible to use Geoportal Server with the AWS OpenSearch or Elastic on Azure PAAS services. This opens the possibility to scale your catalog while also minimizing the maintenance you need to do yourself of the search cluster.

To configure Geoportal Server for use of a cloud-based index, open `app-config.xml` and set:

```
<beans:property name="httpPort" value="443" />
<beans:property name="username" value="your username for the cloud index service" />
<beans:property name="password" value="your password for the cloud index service" />
<beans:property name="useHttps" value="true" />
...
<beans:property name="nodes">
  <!-- The list of host names within the cluster, one value element per host -->
  <beans:list>
    <beans:value>[the open search uri, something like abcdefg-123456.this-region.es.amazonaws.com]</beans:value>
  </beans:list>
</beans:property>

```
For information on how to deploy the Geoportal Server web application in cloud infrastructure as well, we defer to the documentation of your cloud provider. You will find this typically when doing an Internet search for 'deploy tomcat web application <cloud provider>'. We have successfully deployed Geoportal Server in both Azure and AWS with the index provided there as well.

### Configure Elasticsearch for aggregate on built in field(_id) 
This step is only applicable for Elastic 8.x

* Local Elasticsearch
```
Open <elastic_root>\config\elasticsearch.yml and add below line

indices.id_field_data.enabled: true

Save the file and restart Elastic
```

* AWS/AZURE Elastic
```
curl --location --request PUT 'https://4029b37006864504959ec7f6185662ad.westeurope.azure.elastic-cloud.com/_cluster/settings' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic ...' \
--data '{
    "persistent": {
        "indices.id_field_data.enabled": true
    }
}'
```