Set up a sharded cluster

Configure Meilisearch instances into a sharded cluster with replication for horizontal scaling and high availability.

This guide walks you through setting up a Meilisearch cluster with three instances, three shards, and replication for redundancy.

Sharding requires the Meilisearch Enterprise Edition v1.37 or later.

Step 1: Start your instances

Start three Meilisearch instances, each with a master key:

# Instance ms-00
meilisearch --master-key MEILISEARCH_KEY_00 --http-addr 0.0.0.0:7700

# Instance ms-01
meilisearch --master-key MEILISEARCH_KEY_01 --http-addr 0.0.0.0:7701

# Instance ms-02
meilisearch --master-key MEILISEARCH_KEY_02 --http-addr 0.0.0.0:7702

If your instances communicate over a private network, add the --experimental-allowed-ip-networks flag:

meilisearch --master-key MEILISEARCH_KEY --experimental-allowed-ip-networks 10.0.0.0/8,192.168.0.0/16

Step 2: Enable the network feature

Enable the experimental network feature on each instance:

curl \
  -X PATCH 'http://ms-00.example.com:7700/experimental-features' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY_00' \
  --data-binary '{ "network": true }'

Repeat for ms-01 and ms-02 with their respective URLs and master keys.

Step 3: Configure the network topology

Send a single PATCH /network request to the leader instance (ms-00). The leader propagates the configuration to all other remotes automatically. For initial setup, define self, leader, remotes, and shards together:

curl \
  -X PATCH 'http://ms-00.example.com:7700/network' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY_00' \
  --data-binary '{
    "leader": "ms-00",
    "self": "ms-00",
    "remotes": {
      "ms-00": {
        "url": "http://ms-00.example.com:7700",
        "searchApiKey": "SEARCH_KEY_00",
        "writeApiKey": "WRITE_KEY_00"
      },
      "ms-01": {
        "url": "http://ms-01.example.com:7701",
        "searchApiKey": "SEARCH_KEY_01",
        "writeApiKey": "WRITE_KEY_01"
      },
      "ms-02": {
        "url": "http://ms-02.example.com:7702",
        "searchApiKey": "SEARCH_KEY_02",
        "writeApiKey": "WRITE_KEY_02"
      }
    },
    "shards": {
      "shard-a": { "remotes": ["ms-00"] },
      "shard-b": { "remotes": ["ms-01"] },
      "shard-c": { "remotes": ["ms-02"] }
    }
  }'

In this configuration, each shard lives on exactly one remote. Documents are distributed across all three instances, and each instance handles searches for its own shards.

This setup has no replication. If a remote becomes unavailable, its shards are missing from search results. Meilisearch does not yet automatically fall back to another instance. See Configure replication for a high-availability setup.

Step 4: Index documents

Send documents to the leader instance (ms-00). The leader distributes them across shards automatically:

curl \
  -X POST 'http://ms-00.example.com:7700/indexes/movies/documents' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY_00' \
  --data-binary '[
    { "id": 1, "title": "Batman Begins" },
    { "id": 2, "title": "The Dark Knight" },
    { "id": 3, "title": "Spider-Man" }
  ]'

All write operations (document additions, updates, deletions, settings changes) must go through the leader instance. Non-leader instances reject writes with a not_leader error.

Step 5: Search across the cluster

Search requests can be sent to any instance in the network, not just the leader. useNetwork defaults to true when a network topology is defined:

curl \
  -X POST 'http://ms-00.example.com:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer SEARCH_KEY_00' \
  --data-binary '{
    "q": "batman"
  }'

Meilisearch fans out the search to all shards, collects results from each shard, and returns a single merged response.

Verify the topology

Check the current network configuration at any time:

curl \
  -X GET 'http://ms-00.example.com:7700/network' \
  -H 'Authorization: Bearer MEILISEARCH_KEY_00'

Next steps

Manage the network

Add and remove remotes dynamically without reconfiguring the entire topology.

Replication and sharding overview

Understand the concepts behind sharding, replication, and network search.

Data backup

Configure snapshots and dumps for your cluster.