AWS OpenSearch server setup

Available on Enterprise and Enterprise Advanced plans

AWS OpenSearch Service allows you to search large volumes of data quickly, in near real-time, by creating and managing an index of post data. The indexing process can be managed from the System Console after setting up and connecting an OpenSearch server. The post index is stored on the OpenSearch server and updated constantly after new posts are made. In order to index existing posts, a bulk index of the entire post database must be generated.

Deploying AWS OpenSearch includes the following two steps: setting up AWS OpenSearch, and configuring Mattermost.

Set up AWS OpenSearch

From Mattermost v9.11, beta support is available for AWS OpenSearch v1.x and v2.x. This document covers both on‑premises and AWS OpenSearch setup, including manual steps and Terraform examples.

We highly recommend that you set up an AWS OpenSearch server on a separate machine from the Mattermost server.

!Important

Starting in Mattermost v12.0 (October 2026), OpenSearch v1.x is no longer supported. Upgrading to OpenSearch v2.x or later is required.

On-Premises OpenSearch

1. To install on-premise OpenSearch, provision a dedicated server (e.g. Ubuntu 22.04 LTS).

2. Install Java (OpenSearch requires Java 11+):

   sudo apt update 
   sudo apt install -y openjdk-11-jdk 
   java -version

3. Download & extract OpenSearch 2.x:

   wget https://artifacts.opensearch.org/releases/bundle/opensearch/2.9.0/opensearch-2.9.0-linux-x64.tar.gz 
   tar -xzf opensearch-2.9.0-linux-x64.tar.gz 
   sudo mv opensearch-2.9.0 /usr/share/opensearch

4. Create a dedicated user & set permissions:

   sudo useradd --no-create-home --shell /bin/false opensearch 
   sudo chown -R opensearch:opensearch /usr/share/opensearch

5. Configure systemd:

   [Unit] 
     Description=OpenSearch 
     Wants=network-online.target 
     After=network-online.target 
   
   [Service] 
     Type=notify 
     User=opensearch 
     Group=opensearch 
     ExecStart=/usr/share/opensearch/bin/opensearch 
     Restart=on-failure 
     LimitNOFILE=65536 
     LimitNPROC=4096 
   
   [Install] 
     WantedBy=multi-user.target

6. Edit opensearch.yml to include the following:

   cluster.name: mattermost-cluster
   node.name: node-1
   path.data: /var/lib/opensearch
   path.logs: /var/log/opensearch
   network.host: 0.0.0.0
   discovery.seed_hosts: ["<other-node-ip>"]
   cluster.initial_master_nodes: ["node-1", "node-2"]

   iNote

   Ensure path.data and path.logs directories exist and are owned by the opensearch user before starting the service:

   sudo mkdir -p /var/lib/opensearch /var/log/opensearch
   sudo chown -R opensearch:opensearch /var/lib/opensearch /var/log/opensearch

7. Enable & start OpenSearch:

   sudo systemctl daemon-reload 
   sudo systemctl enable opensearch 
   sudo systemctl start opensearch 
   sudo systemctl status opensearch

8. Install the icu-analyzer plugin to the /usr/share/opensearch/plugins directory by running the following command:

   !Important

   The analysis-icu plugin is required on every node in the cluster, not optional. Mattermost's post and file index templates depend on it. Without the plugin, Mattermost cannot create these templates.

   sudo /usr/share/opensearch/bin/opensearch-plugin install analysis-icu

   Restart OpenSearch on each node to load the newly installed plugin before verifying it; _cat/plugins only reports active plugins, so a restart is required first. For production clusters, restart nodes one at a time (rolling restart) rather than all at once. Confirm the plugin is installed and active on every node before continuing. Replace the host, admin password, and path to your cluster's CA certificate:

   curl --silent --show-error --fail-with-body --cacert <path-to-root-ca.pem> --user 'admin:<password>' 'https://<your-opensearch-host>:9200/_cat/plugins?v&h=name,component,version&s=name,component'

   Running this command should show analysis-icu once per node in the cluster. If the analysis-icu line is missing for any node, the plugin is not installed there.

(Optional) CJK language analyzer plugins: To improve search for Korean, Japanese, or Chinese content, install one or more of the following language-specific analyzer plugins: analysis-nori (Korean), analysis-kuromoji (Japanese), and analysis-smartcn (Chinese).

sudo /usr/share/opensearch/bin/opensearch-plugin install analysis-nori
sudo /usr/share/opensearch/bin/opensearch-plugin install analysis-kuromoji
sudo /usr/share/opensearch/bin/opensearch-plugin install analysis-smartcn

After installing the CJK plugins, restart OpenSearch to load them:

sudo systemctl restart opensearch

Then enable the EnableCJKAnalyzers configuration setting. See Enabling Chinese, Japanese, and Korean Search for additional CJK search configuration options.

!Important

If you enable CJK analyzers on a server with existing indexed content, you must purge and rebuild the search index in System Console > Environment > Elasticsearch for the CJK analyzers to take effect on existing posts.

Terraform (Docker) Example

provider "docker" { 
  host = "unix:///var/run/docker.sock" 
}

resource "docker_image" "opensearch" { 
  name = "opensearchproject/opensearch:2.9.0" 
}

resource "docker_container" "opensearch" { 
  name = "opensearch" 
  image = docker_image.opensearch.latest 

  ports { 
    internal = 9200 
    external = 9200 
  }
  ports { 
    internal = 9600 
    external = 9600 
  }

  env = [
    "cluster.name=mattermost-cluster",
    "network.host=0.0.0.0",
    "discovery.type=single-node", # remove for multi-node 
  ]

  restart = "unless-stopped" 
}

resource "null_resource" "install_icu_plugin" {
  depends_on = [docker_container.opensearch]

  provisioner "local-exec" {
    command = "docker exec opensearch /usr/share/opensearch/bin/opensearch-plugin install analysis-icu && docker restart opensearch"
  }
}

AWS OpenSearch Console Setup

1. To install AWS OpenSearch, open the AWS Console > OpenSearch Service.

2. Create a domain, where:

   • Domain name: mattermost-os
   • Engine version: OpenSearch 2.x.

3. Configure the cluster, where:

   • instance type: r6g.xlarge.search
   • data nodes: 2
   • master nodes: 2
   • storage: EBS gp3 (1536 GiB, 4608 IOPS, 250 MiB/s)

4. Specify the network for: VPC with 2 subnets, and a security group allowing Mattermost IPs on port 443.

iNote

Port 9200 is commonly used for local or on-premise OpenSearch. The AWS OpenSearch domain only supports HTTPS over port 443.

5. Configure the access policy (JSON). Mattermost doesn't sign OpenSearch requests with AWS SigV4, so restrict access at the network layer with the VPC and security group from step 4, and use an open principal in the domain access policy:

   {
     "Version": "2012-10-17",
     "Statement": [{
       "Effect": "Allow",
       "Principal": { "AWS": "*" },
       "Action": "es:ESHttp*",
       "Resource": "arn:aws:es:us-east-1:123456789012:domain/mattermost-os/*" }]
   }

!Warning

IAM principal-based access policies (for example, "Principal": { "AWS": "arn:aws:iam::<account-id>:role/<role-name>" }) are not supported. Mattermost's OpenSearch client doesn't sign requests with AWS SigV4, so AWS treats the requests as anonymous and an IAM-restricted policy will reject them with User: anonymous is not authorized to perform: es:ESHttpGet. If you need authentication enforced at the OpenSearch layer rather than the network layer, enable fine-grained access control on the domain with an internal master user, and enter those credentials as the Server Username and Server Password in the Mattermost Elasticsearch configuration.

6. Configure the following advanced settings (JSON):

   {
     "action.destructive_requires_name": "false", 
     "rest.action.multi.allow_explicit_index": "true", 
     "indices.query.bool.max_clause_count": "1024", 
     "indices.fielddata.cache.size": "20" 
   }

7. Configure the automated snapshot start hour as 23 (UTC), enforce HTTPS, then review & create.

8. To test, run the following command:

   curl https://mattermost-os-xxxxxxxxxxx.us-east-1.es.amazonaws.com

AWS Terraform Example

provider "aws" { 
  region = "us-east-1" 
}

resource "aws_iam_role" "os_service_role" { 
  name = "OSServiceRole" 
  assume_role_policy = <<EOF 
{
  "Version": "2012-10-17", 
  "Statement": [{ 
    "Action": "sts:AssumeRole", 
    "Effect": "Allow", 
    "Principal": { "Service": "es.amazonaws.com" } 
  }]
}
EOF
}

resource "aws_opensearch_domain" "mattermost" { 
  domain_name = "mattermost-os" 
  engine_version = "OpenSearch_2.9"
  cluster_config { 
    instance_type = "r6g.xlarge.search" 
    instance_count = 2 
    dedicated_master_enabled = true 
    dedicated_master_type = "r6g.xlarge.search" 
    dedicated_master_count = 2 
    zone_awareness_enabled = true 
  }

  ebs_options { 
    ebs_enabled = true 
      volume_type = "gp3" 
      volume_size = 1536 
      iops = 4608 
  }

  vpc_options { 
    subnet_ids = ["subnet-blah1", "subnet-blah2"] 
    security_group_ids = ["sg-1234567890"] 
  }

  advanced_options = { 
    "rest.action.multi.allow_explicit_index" = "true" 
    "indices.query.bool.max_clause_count" = "1024" 
    "indices.fielddata.cache.size" = "20" 
    "action.destructive_requires_name" = "false" 
  }

  access_policies = <<POLICY 
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "AWS": "*"
    },
      "Action": "es:ESHttp*",
      "Resource": "arn:aws:es:us-east-1:123456789012:domain/mattermost-os/*" 
    }]
  }
  POLICY
    service_software_options { 
      automated_snapshot_start_hour = 23 
    }

    domain_endpoint_options { 
      enforce_https = true 
    }
}

Configure Mattermost

Follow these steps to configure Mattermost to use your AWS OpenSearch server and to generate the post index:

1. Go to System Console > Environment > Elasticsearch.
2. Set Enable Elasticsearch Indexing to true to enable the other the settings on the page.
3. Ensure Backend type is set to opensearch.
4. Set the Server Connection Address to your Elasticsearch or OpenSearch cluster endpoint.
5. Monitor cluster health: curl https://mattermost-os-xxxxx.us-east-1.es.amazonaws.com/_cluster/health

1. (Optional) Enter Server Username used to access the enterprise search server.
2. (Optional) Enter Server Password associated with the username.
3. Set Enable Cluster Sniffing (Optional). Sniffing finds and connects to all data nodes in your cluster automatically.

!Warning

Do not enable cluster sniffing when using cloud-hosted search providers such as Elastic Cloud or Amazon OpenSearch Service. Cloud providers typically hide search cluster nodes behind a proxy, so sniffed node addresses may be unreachable from your network. The provider handles connection pooling for you, making sniffing unnecessary and potentially disruptive.

4. Optional CA and client certificate configuration settings are available for use with basic authentication credentials or to replace them. See the Enterprise search configuration settings documentation for details.
5. Select Test Connection and then select Save. If the server connection is unsuccessful you won't be able to save the configuration or enable searching with Elasticsearch or AWS OpenSearch.

iNote

From Mattermost v11, enterprise search server connections are tested during Support Packet generation. Any connection errors encountered during Support Packet generation are automatically included in the packet to help diagnose configuration issues.

Build the post index of existing messages

Select Index Now. This process can take up to a few hours depending on the size of the post database and number of messages. The progress percentage can be seen as the index is created. To avoid downtime, set Enable Elasticsearch for search queries to false so that database search is available during the indexing process.

Enable enterprise search

Ensure bulk indexing is complete before enabling enterprise search, otherwise search results will be incomplete.

Set Enable Elasticsearch for search queries to true, and setting Enable Elasticsearch for autocomplete to true. Save your configuration updates and restart the Mattermost server.

iNote

For high post volume deployments, we strongly encourage you to read and properly configure the Mattermost LiveIndexingBatchSize configuration setting.

!Warning

For high post volume deployments, we also strongly recommend disabling Database Search once Elasticsearch or AWS OpenSearch is fully configured and running. The Mattermost Server will fall back on Database search if Elasticsearch or OpenSearch are unavailable, which can lead to performance degradation on high post volume deployments. From Mattermost v11.7, the server proactively detects outages through periodic health checks and falls back to database search on the first health check failure, rather than waiting for requests to time out. See the outage handling FAQ for details.

Once the configuration is saved, new posts made to the database are automatically indexed on the Elasticsearch or AWS OpenSearch server.

Enterprise search limitations

1. Elasticsearch and AWS OpenSearch use a standard selection of "stop words" to keep search results relevant. Results for the following words will not be returned: "a", "an", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", and "with".
2. Searching stop words in quotes returns more results than just the searched terms (ticket).
3. By default, search results are limited to a user's team and channel membership. This is enforced by the Mattermost server. The entities are indexed in Elasticsearch or AWS OpenSearch in a way that allows Mattermost to filter them when querying, so the Mattermost server narrows down the results on every Elasticsearch or AWS OpenSearch request applying those filters. From Mattermost v11.6, admins can allow searching public channels without membership so that users can find messages in public channels they haven't joined, scoped to teams they belong to.
4. User search and autocomplete served by Elasticsearch or AWS OpenSearch match on username, nickname, and first and last name only. Email addresses aren't indexed, so no user can be found by email address, including system admins. User searches served from the database continue to match on email address. For channel and team member searches, system admins always match on email address, and all other users also require Show email address to be enabled. The System Console > User Management > Users list always matches on email address, independently of that setting.