Skip to main content
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 PATCH /network request to each instance. The configuration is identical across instances except for the self field, which identifies the current instance: 
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"
      },
      "ms-01": {
        "url": "http://ms-01.example.com:7701",
        "searchApiKey": "SEARCH_KEY_01"
      },
      "ms-02": {
        "url": "http://ms-02.example.com:7702",
        "searchApiKey": "SEARCH_KEY_02"
      }
    }
  }'
Send the same request to ms-01 (with "self": "ms-01") and ms-02 (with "self": "ms-02").

​
Step 4: Configure shards

Define how documents are distributed across remotes. Each shard is assigned to one or more remotes: 
curl \
  -X PATCH 'http://ms-00.example.com:7700/network' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY_00' \
  --data-binary '{
    "shards": {
      "shard-a": { "remotes": ["ms-00", "ms-01"] },
      "shard-b": { "remotes": ["ms-01", "ms-02"] },
      "shard-c": { "remotes": ["ms-02", "ms-00"] }
    }
  }'
In this configuration, each shard is replicated across two remotes. If any single instance goes down, all shards remain available through the other instance.

​
Step 5: 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_a_leader error.

​
Step 6: Search across the cluster

Search with useNetwork: true to query all remotes: 
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",
    "useNetwork": true
  }'
Meilisearch fans out the search to all remotes, 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.