Opensearch Setup

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

import Inc0_common_configure_mattermost_for_enterprise_search from './common-configure-mattermost-for-enterprise-search.mdx';

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.

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

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

Install Java (OpenSearch requires Java 11+):

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

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

Create a dedicated user & set permissions:

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

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

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"]

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

Enable & start OpenSearch:

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

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

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.

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"
  }
}

To install AWS OpenSearch, open the AWS Console > OpenSearch Service.
Create a domain, where:
- Domain name: mattermost-os
- Engine version: OpenSearch 2.x.
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)
Specify the network for: VPC with 2 subnets, and a security group allowing Mattermost IPs on port 443.

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

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/*" }]
}

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.

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" 
}

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

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:

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