ElasticSearch

ElasticSearch is a distributed search engine that can serve as the search store. It moves the indexing and search load of a large installation to a cluster of its own, which is scaled separately from Stalwart. Stalwart creates the indexes it needs on first use, so no index has to be prepared in advance.

Configuration

The backend is selected with the ElasticSearch variant of the SearchStore object (found in the WebUI under Settings › Storage › Search Store). url is the address of the ElasticSearch server or of the cluster endpoint. timeout limits the duration of each HTTP request. allowInvalidCerts accepts an invalid TLS certificate, and httpHeaders adds headers to every request.

httpAuth selects how Stalwart authenticates to ElasticSearch. A server without authentication uses Unauthenticated. Basic sends a username and a secret, and Bearer sends a bearerToken, for example an ElasticSearch API key. Secrets can be given as a value, read from an environment variable or read from a file.

The following search store connects to an ElasticSearch cluster with a user name and a password read from a file:

{
  "@type": "ElasticSearch",
  "url": "https://es.example.com:9200",
  "httpAuth": {
    "@type": "Basic",
    "username": "stalwart",
    "secret": {"@type": "File", "filePath": "/run/secrets/es-password"}
  },
  "numReplicas": 1
}

Index settings

Three fields determine the shape of the indexes that Stalwart creates. They are applied only when an index is created, and an existing index keeps the settings it was created with:

• numShards: the number of primary shards of each index. ElasticSearch splits an index into shards to spread it over its nodes.
• numReplicas: the number of replicas of each primary shard, 0 unless changed. A replica is needed for the index to survive the loss of an ElasticSearch node.
• includeSource: whether ElasticSearch keeps the original indexed document (the _source field) in addition to the index. Enabling it increases the size of the index.

Changing these settings later differs by setting. The number of replicas of an existing index can be changed with the ElasticSearch update index settings API. Changing the number of shards or includeSource, on the other hand, requires deleting the indexes in ElasticSearch and rebuilding the index.