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

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.

#!/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 at lines 5-6, with identical logic in entrypoint-shard02.sh and 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 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.

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 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 contains:

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:

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

Key Files and Their Roles in Shard Initialization

• scripts/entrypoint-shard01.sh, scripts/entrypoint-shard02.sh, 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, scripts/init-shard02.js, scripts/init-shard03.js – Standalone JavaScript files containing the replica set configuration for manual initialization scenarios.

• 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, entrypoint-shard02.sh, and entrypoint-shard03.sh, with identical patterns across all shards.
• Manual initialization alternatives are available via 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, init-shard02.js, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}