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

> Discover how the MongoDB config server replica set is configured and managed within Docker Compose. Learn about auto-initialization with rs initiate and the configsvr flag.

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

---

**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/main/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:

```yaml
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/main/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:

```javascript
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:

```bash
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:

```json
{
  "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:

```bash
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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/docker-compose.yml) with the `--configsvr` flag enabled.
- **Automatic initialization** is handled by [`entrypoint-configserver.sh`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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.