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

> Deploy a minimal MongoDB sharded cluster easily with the minimize folder. This guide shows a lightweight Docker Compose setup for config servers, shards, and query routers.

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

---

**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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/minimize/docker-compose.yml) | Defines all services, port mappings, volume mounts, and container dependencies |
| [`minimize/scripts/init-configserver.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/minimize/scripts/init-configserver.js) | Initializes the config server replica set using `rs.initiate()` |
| [`minimize/scripts/init-shard01.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/minimize/scripts/init-shard01.js) | Configures the first shard's replica set with three members |
| [`minimize/scripts/init-shard02.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/minimize/scripts/init-shard02.js) | Configures the second shard's replica set with three members |
| [`minimize/scripts/init-router.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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:

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

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

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

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

```

The [`init-router.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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:

```bash
docker-compose exec router01 mongosh --port 27017

```

Inside the mongosh shell:

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

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

```

**Verify replica set configuration for Shard 01:**

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

```

**Verify replica set configuration for Shard 02:**

```bash
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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/docker-compose.yml) following the `shard02-*` pattern
2. Execute [`minimize/scripts/update01/init-shard03.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/minimize/scripts/update01/init-shard03.js) against the new shard's primary node
3. Re-run [`minimize/scripts/init-router.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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:

```bash
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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/docker-compose.yml) as a template, create a new initialization script following the pattern in [`update01/init-shard03.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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.