# Replica Set Initialization for Each Shard in a MongoDB Docker Compose Cluster

> Learn how MongoDB replica set initialization works for each shard in a Docker Compose cluster. Discover the automated entrypoint script process.

- Repository: [Jin/mongodb-cluster-docker-compose](https://github.com/minhhungit/mongodb-cluster-docker-compose)
- Tags: how-to-guide
- Published: 2026-03-07

---

**Each shard in the MongoDB cluster automatically initializes its three-member replica set through entrypoint scripts that start the mongod process, wait for all nodes to become reachable, and execute `rs.initiate()` with the proper configuration.**

The `minhhungit/mongodb-cluster-docker-compose` repository automates the deployment of a sharded MongoDB cluster using Docker Compose. Understanding the **replica set initialization for each shard** is critical for maintaining high availability and data redundancy across the distributed architecture.

## How Replica Set Initialization Works for MongoDB Shards

When the Docker Compose stack launches, every shard runs a dedicated container that executes a bash entrypoint script. The initialization follows an identical pattern across all three shards (**shard-01**, **shard-02**, and **shard-03**), ensuring consistency and reliability. The process involves starting the MongoDB instance with specific shard server parameters, verifying network connectivity to all replica set members, and formally initiating the replica set configuration.

## Step-by-Step Shard Replica Set Initialization Process

### Step 1: Starting the MongoDB Shard Server

The entrypoint script begins by launching `mongod` as a shard server with the `--shardsvr` flag and binding it to all interfaces. This command runs in the background so the script can proceed with health checks.

```bash
#!/bin/bash
set -e

# Start mongod as a shard server

mongod --shardsvr --replSet rs-shard-01 --port 27017 --bind_ip_all &

MONGO_PID=$!
sleep 5

```

This configuration appears in [`scripts/entrypoint-shard01.sh`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/entrypoint-shard01.sh) at lines 5-6, with identical logic in [`entrypoint-shard02.sh`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/entrypoint-shard02.sh) and [`entrypoint-shard03.sh`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/entrypoint-shard03.sh) for their respective replica set IDs (`rs-shard-02` and `rs-shard-03`).

### Step 2: Waiting for Shard Members to Become Reachable

Before initializing the replica set, the script ensures all three members of the shard are network-accessible. It implements a retry loop that pings the local instance (`127.0.0.1`) and the two remote members (designated as `shardXX-b` and `shardXX-c` in the Docker network).

The wait logic, found in [`scripts/entrypoint-shard01.sh`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/entrypoint-shard01.sh) at lines 20-52, performs the following checks:

- Verifies the local `mongod` process is still running
- Attempts connection to `127.0.0.1:27017`, `shard01-b:27017`, and `shard01-c:27017`
- Aborts after a configurable number of failed attempts to prevent infinite loops

This synchronization ensures that `rs.initiate()` only executes when the replica set can form a valid quorum.

### Step 3: Executing rs.initiate() to Form the Replica Set

Once all members are reachable, the script uses `mongosh` to execute the `rs.initiate()` command with a configuration object defining the replica set ID and the three member nodes.

```javascript
mongosh --eval '
  rs.initiate({
    _id: "rs-shard-01",
    version: 1,
    members: [
      { _id: 0, host : "shard01-a:27017" },
      { _id: 1, host : "shard01-b:27017" },
      { _id: 2, host : "shard01-c:27017" }
    ]
  })
'

```

This initialization code appears in [`scripts/entrypoint-shard01.sh`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/entrypoint-shard01.sh) at lines 65-74. The corresponding scripts for shard-02 and shard-03 contain identical logic with their respective replica set names (`rs-shard-02`, `rs-shard-03`) and hostnames (`shard02-a/b/c`, `shard03-a/b/c`).

## Alternative Manual Initialization Method

While the entrypoint scripts automate the process, the repository also provides standalone JavaScript files for manual initialization. These files contain the same `rs.initiate()` configuration and can be executed via `mongosh` when troubleshooting or performing maintenance.

For example, [`scripts/init-shard01.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/init-shard01.js) contains:

```javascript
rs.initiate({
    _id: "rs-shard-01",
    version: 1,
    members: [
        { _id: 0, host : "shard01-a:27017" },
        { _id: 1, host : "shard01-b:27017" },
        { _id: 2, host : "shard01-c:27017" }
    ]
});

```

To manually initialize shard-02, execute:

```bash
docker exec -it shard-02-node-a mongosh /scripts/init-shard02.js

```

## Key Files and Their Roles in Shard Initialization

- **[`scripts/entrypoint-shard01.sh`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/entrypoint-shard01.sh)**, **[`scripts/entrypoint-shard02.sh`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/entrypoint-shard02.sh)**, **[`scripts/entrypoint-shard03.sh`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/entrypoint-shard03.sh)** – Bash entrypoint scripts that start mongod, wait for connectivity, and execute `rs.initiate()` for each respective shard.

- **[`scripts/init-shard01.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/init-shard01.js)**, **[`scripts/init-shard02.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/init-shard02.js)**, **[`scripts/init-shard03.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/init-shard03.js)** – Standalone JavaScript files containing the replica set configuration for manual initialization scenarios.

- **[`docker-compose.yml`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/docker-compose.yml)** – Defines the three shard services (`shard-01-node-a`, `shard-01-node-b`, `shard-01-node-c`, etc.) and mounts the entrypoint scripts into the containers.

## Summary

- Each shard in the `minhhungit/mongodb-cluster-docker-compose` cluster uses a dedicated entrypoint script to automate **replica set initialization**.
- The process follows three distinct phases: starting the mongod shard server, waiting for all three members to become reachable, and executing `rs.initiate()` with the proper configuration.
- The initialization logic resides in [`scripts/entrypoint-shard01.sh`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/entrypoint-shard01.sh), [`entrypoint-shard02.sh`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/entrypoint-shard02.sh), and [`entrypoint-shard03.sh`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/entrypoint-shard03.sh), with identical patterns across all shards.
- Manual initialization alternatives are available via [`scripts/init-shardXX.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/init-shardXX.js) files for troubleshooting or maintenance scenarios.
- The initialization only runs during the first container start; subsequent restarts skip `rs.initiate()` because the replica set metadata already persists.

## Frequently Asked Questions

### How many members are in each shard replica set?

Each shard replica set consists of **three members**, designated as nodes A, B, and C (for example, `shard01-a`, `shard01-b`, and `shard01-c`). This three-member configuration provides automatic failover and data redundancy while maintaining a quorum for election purposes.

### What happens if the replica set is already initialized when the container restarts?

The entrypoint scripts are designed to be idempotent. During subsequent container restarts, the `mongod` process starts normally, but the `rs.initiate()` command fails because the replica set configuration already exists. The script captures this failure with `|| echo "Failed to initialize replica set"` and continues, allowing the node to rejoin the existing replica set without errors.

### Can I initialize the shard replica sets manually instead of using the entrypoint scripts?

Yes, the repository provides standalone JavaScript files ([`scripts/init-shard01.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/init-shard01.js), [`init-shard02.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/init-shard02.js), [`init-shard03.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/init-shard03.js)) that contain the exact `rs.initiate()` configuration used by the automated scripts. You can execute these manually using `docker exec -it <container> mongosh /scripts/init-shardXX.js` when troubleshooting, performing maintenance, or if you prefer to disable the automatic entrypoint initialization.

### What is the naming convention for replica set IDs in this cluster?

Each shard follows a consistent naming pattern where the replica set ID corresponds to the shard number. **Shard-01** uses `rs-shard-01`, **shard-02** uses `rs-shard-02`, and **shard-03** uses `rs-shard-03`. This naming convention appears in the `--replSet` parameter of the `mongod` command and in the `_id` field of the `rs.initiate()` configuration object.