How the Config Server Replica Set Is Configured and Managed in MongoDB Docker Clusters

The config server replica set is initialized by a custom entrypoint script on the first container that waits for all three members to become reachable before executing rs.initiate() with the configsvr: true flag.

In a MongoDB sharded cluster, the config server replica set stores critical metadata about chunk distributions, shard mappings, and cluster-wide settings. The minhhungit/mongodb-cluster-docker-compose repository automates the deployment and management of this replica set using Docker Compose and specialized shell scripts. Understanding this configuration helps you maintain high availability and troubleshoot initialization failures in containerized MongoDB environments.

Architecture of the Config Server Replica Set

The deployment creates a three-member replica set named rs-config-server that provides redundancy for the cluster's metadata layer. Each member runs as a separate Docker container with distinct responsibilities within the sharded cluster topology.

Service Definitions in Docker Compose

The three config server containers are declared in [docker-compose.yml](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/master/docker-compose.yml) (lines 15-44):

• configsvr01 (mongo-config-01): Designated entry-point container that handles replica set initialization
• configsvr02 (mongo-config-02): Standard replica set member
• configsvr03 (mongo-config-03): Standard replica set member

The key configuration differences appear in the service definitions:

configsvr01:
  image: mongo:latest
  container_name: mongo-config-01
  volumes: [...]
  restart: always
  entrypoint: ["/scripts/entrypoint-configserver.sh"]

configsvr02:
  image: mongo:latest
  container_name: mongo-config-02
  command: mongod --port 27017 --configsvr --replSet rs-config-server

configsvr03:
  image: mongo:latest
  container_name: mongo-config-03
  command: mongod --port 27017 --configsvr --replSet rs-config-server

Initialization and Management Process

The config server replica set requires explicit initialization through MongoDB's rs.initiate() command. The repository handles this automatically through a specialized entrypoint script that coordinates the startup sequence across all three containers.

The Entrypoint Script Logic

The [scripts/entrypoint-configserver.sh](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/master/scripts/entrypoint-configserver.sh) file contains the initialization logic executed exclusively by configsvr01. The script performs three critical operations:

1. Background MongoDB Startup: Launches mongod with --configsvr and --replSet rs-config-server flags
2. Health Check Coordination: Polls all three config servers (configsvr01, configsvr02, configsvr03) using mongosh until they respond to ping commands, preventing race conditions during initialization
3. Replica Set Initialization: Executes rs.initiate() with the specific configuration object:

rs.initiate({
  _id: "rs-config-server",
  configsvr: true,
  version: 1,
  members: [
    { _id: 0, host: "configsvr01:27017" },
    { _id: 1, host: "configsvr02:27017" },
    { _id: 2, host: "configsvr03:27017" }
  ]
})

After initialization, the script enters a wait state (wait $MONGO_PID) to keep the container running indefinitely.

Ongoing Management and Failover

Once initialized, the config server replica set operates autonomously without requiring external orchestration:

• Automatic Recovery: All containers specify restart: always, ensuring failed nodes restart automatically
• Internal Election: MongoDB's native replication protocol handles primary elections if the current primary fails
• Service Discovery: The Docker Compose internal DNS resolves hostnames (configsvr01, configsvr02, configsvr03) used in the replica set configuration, eliminating the need for static IP addresses

Verification and Operational Commands

To confirm the config server replica set is functioning correctly, you can inspect the replica set status from any member.

Checking Replica Set Health

Connect to the primary config server container and execute the status command:

docker exec -it mongo-config-01 mongosh --host localhost --eval "rs.status()"

A healthy replica set returns JSON showing one PRIMARY and two SECONDARY members:

{
  "set": "rs-config-server",
  "myState": 1,
  "members": [
    { "_id": 0, "name": "configsvr01:27017", "stateStr": "PRIMARY" },
    { "_id": 1, "name": "configsvr02:27017", "stateStr": "SECONDARY" },
    { "_id": 2, "name": "configsvr03:27017", "stateStr": "SECONDARY" }
  ]
}

Manual Reconfiguration After Node Failure

If a config server becomes permanently unavailable, remove it from the replica set configuration:

docker exec -it mongo-config-01 mongosh --eval "
  cfg = rs.conf()
  cfg.members = cfg.members.filter(m => m.host !== 'configsvr02:27017')
  rs.reconfig(cfg, { force: true })
"

Summary

• The config server replica set (rs-config-server) consists of three containers defined in docker-compose.yml with the --configsvr flag enabled.
• Automatic initialization is handled by entrypoint-configserver.sh on configsvr01, which waits for all members to become healthy before executing rs.initiate().
• High availability is maintained through MongoDB's native replication elections and Docker's restart: always policy, requiring no external orchestration for failover.
• Operational verification uses standard MongoDB commands like rs.status() to confirm primary and secondary member states.

Frequently Asked Questions

What is the purpose of the config server replica set in a MongoDB sharded cluster?

The config server replica set stores the cluster's metadata, including the mapping of chunks to shards, authentication configuration, and cluster-wide settings. Without this metadata layer, the mongos query routers cannot determine where to route read and write operations. The replica set architecture ensures this critical metadata remains available even if individual config servers fail.

Why does only the first config server run the initialization script?

The configsvr01 container executes entrypoint-configserver.sh to prevent split-brain initialization scenarios where multiple nodes might attempt to form separate replica sets simultaneously. By designating a single entry point that waits for all peers to become reachable before calling rs.initiate(), the repository ensures a clean, consistent initialization of the rs-config-server replica set. The other two containers simply start mongod and wait for the primary to initiate them into the set.

How does the cluster handle config server failure and recovery?

If a config server container stops or crashes, Docker's restart: always policy automatically attempts to restart it. Once the node rejoins the network, MongoDB's replication protocol synchronizes any missed oplog entries to bring it back to a consistent state. If the former primary fails, the remaining secondaries hold an election to promote a new primary. For permanent node loss, administrators can use rs.reconfig() to remove the defunct member, though the system continues operating with two nodes until replaced.

Can I scale the config server replica set to more than three members?

Yes, MongoDB supports up to seven voting members in a config server replica set. To add additional nodes, define new services in docker-compose.yml using the same --configsvr --replSet rs-config-server command structure, then use rs.add() from the primary to incorporate them into the set. However, three members are generally sufficient for most production deployments, as the config servers only handle metadata operations rather than application data traffic.

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