How to Deploy a Minimal MongoDB Sharded Cluster Using the Minimize Folder

The minimize folder provides a lightweight Docker Compose configuration that deploys a fully functional MongoDB sharded cluster with the minimum number of containers required to demonstrate config servers, shard replica sets, and query routing.

The minimize folder in the minhhungit/mongodb-cluster-docker-compose repository offers a compact, production-like environment for learning MongoDB sharding without the overhead of a full-scale deployment. This directory contains a complete Docker Compose setup using the official mongo:6.0.1 image, initialization scripts for replica sets, and configuration files that bind services to host ports for easy access.

Core Architecture and Components

The minimize folder deploys a minimal yet complete sharded cluster architecture. Each component runs as a separate container defined in minimize/docker-compose.yml, with shared volumes mounting the minimize/scripts directory for initialization.

Config Server Replica Set

• Container: configsvr01 (mapped to mongo-config-01)
• Replica Set: rs-config-server
• Port: Exposed on host port 27019
• Purpose: Stores metadata and configuration settings for the cluster

Shard Replica Sets

Two distinct shards provide horizontal scaling capabilities:

• Shard 01: Three containers (shard01-a, shard01-b, shard01-c) forming replica set rs-shard-01, exposed on ports 27018 (primary) and internal ports for secondaries
• Shard 02: Three containers (shard02-a, shard02-b, shard02-c) forming replica set rs-shard-02, exposed on ports 27028 (primary) and internal ports for secondaries

Query Router (Mongos)

• Container: router01 (mapped to router-01)
• Port: Exposed on host port 27017
• Purpose: Acts as the entry point for client applications, routing queries to appropriate shards

Key Files and Their Roles

The minimize directory contains several critical files that automate cluster initialization:

File	Purpose
minimize/docker-compose.yml	Defines all services, port mappings, volume mounts, and container dependencies
minimize/scripts/init-configserver.js	Initializes the config server replica set using rs.initiate()
minimize/scripts/init-shard01.js	Configures the first shard's replica set with three members
minimize/scripts/init-shard02.js	Configures the second shard's replica set with three members
minimize/scripts/init-router.js	Adds both shards to the cluster via sh.addShard() commands
minimize/scripts/update01/	Contains optional scripts for adding a third shard to an existing cluster

Step-by-Step Deployment Guide

Deploying the minimal cluster requires starting containers in sequence and running initialization scripts against specific replica set members.

Starting the Infrastructure

Navigate to the minimize directory and start all containers:

cd minimize
docker-compose up -d

This command creates and starts the config server, six shard nodes (three per shard), and the query router. The -d flag runs containers in detached mode.

Initializing the Config Server

Run the config server initialization script against the primary config server container:

docker-compose exec configsvr01 sh -c "mongosh < /scripts/init-configserver.js"

This script executes rs.initiate() to create the rs-config-server replica set, establishing the metadata store required before shards can join the cluster.

Initializing the Shard Replica Sets

Initialize each shard's replica set by executing their respective scripts against the first node of each shard:

docker-compose exec shard01-a sh -c "mongosh < /scripts/init-shard01.js"
docker-compose exec shard02-a sh -c "mongosh < /scripts/init-shard02.js"

Each script configures a three-member replica set (rs-shard-01 and rs-shard-02) with the -a container as the initial primary.

Configuring the Query Router

Wait approximately 10-15 seconds for the config server and shards to complete primary elections, then initialize the router:

docker-compose exec router01 sh -c "mongosh < /scripts/init-router.js"

The init-router.js script connects the router to the config server and registers both shards using sh.addShard("rs-shard-01/shard01-a:27017") and equivalent commands for shard 02.

Enabling Sharding on Databases and Collections

Connect to the router to enable sharding for specific databases and collections:

docker-compose exec router01 mongosh --port 27017

Inside the mongosh shell:

// Enable sharding on a database
sh.enableSharding("MyDatabase")

// Shard a collection with a compound key
db.adminCommand({
  shardCollection: "MyDatabase.MyCollection",
  key: { oemNumber: "hashed", zipCode: 1, supplierId: 1 }
})

This configuration uses a hashed shard key on oemNumber combined with range-based sharding on zipCode and supplierId.

Verification and Health Checks

Verify the cluster is operational by checking the sharding status and replica set health:

Check overall cluster status:

docker-compose exec router01 mongosh --port 27017 --eval "sh.status()"

Verify replica set configuration for Shard 01:

docker exec -it shard-01-node-a bash -c "echo 'rs.status()' | mongosh --port 27017"

Verify replica set configuration for Shard 02:

docker exec -it shard-02-node-a bash -c "echo 'rs.status()' | mongosh --port 27017"

Each command should return JSON showing one PRIMARY and two SECONDARY members per replica set, confirming proper initialization.

Extending the Cluster with Additional Shards

The minimize/scripts/update01 directory contains templates for horizontal scaling. To add a third shard:

1. Add new shard container definitions to docker-compose.yml following the shard02-* pattern
2. Execute minimize/scripts/update01/init-shard03.js against the new shard's primary node
3. Re-run minimize/scripts/init-router.js or execute sh.addShard() manually to register the new shard with the router

This approach allows the minimal cluster to grow from two shards to three or more without requiring a full redeployment.

Summary

• The minimize folder provides a lightweight Docker Compose setup for deploying a complete MongoDB sharded cluster using the official mongo:6.0.1 image.
• The deployment includes one config server replica set, two shard replica sets (three members each), and one mongos router, all defined in minimize/docker-compose.yml.
• Initialization scripts in minimize/scripts/ automate replica set configuration and shard registration, requiring sequential execution against specific containers.
• The setup exposes standard MongoDB ports on the host (27017 for router, 27018/27028 for shards, 27019 for config server) for easy client access.
• The update01 folder provides templates for adding additional shards to an existing cluster without full redeployment.

Frequently Asked Questions

What is the difference between the minimize folder and the root docker-compose.yml?

The root directory typically contains a production-scale configuration with additional monitoring, volume persistence, and networking options, while the minimize folder specifically provides a stripped-down version that runs the minimum viable sharded cluster (config server + 2 shards + router) for development, testing, and learning purposes. The minimize configuration uses the mongo:6.0.1 image and exposes ports directly on the host for simplified access.

How do I connect to the cluster from a MongoDB client?

Connect to the router (mongos) container which acts as the single entry point for the entire cluster. Use the host port 27017 with standard MongoDB connection strings:

mongosh "mongodb://localhost:27017/MyDatabase"

Or for drivers: mongodb://localhost:27017. Do not connect directly to individual shard nodes (ports 27018, 27028) for application queries, as the router handles query distribution and result aggregation.

Can I add more shards after the initial deployment?

Yes, the minimize/scripts/update01 directory contains templates and scripts for horizontal scaling. To add a third shard, copy the shard container definitions from docker-compose.yml as a template, create a new initialization script following the pattern in update01/init-shard03.js, and execute sh.addShard() from the router or re-run the router initialization script. This allows the cluster to grow from two shards to three or more without requiring a complete teardown and rebuild.

Why does the router initialization fail with "config server not found" errors?

This occurs when the config server replica set has not yet elected a primary or fully initialized before the router attempts to connect. The config server must complete its rs.initiate() command and elect a primary (typically 10-15 seconds) before the router can register shards. Always initialize the config server first, wait for the replica set to stabilize, then initialize the shards, and finally run the router initialization script.

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