How to Reset and Reinitialize a MongoDB Cluster in Docker Compose: Complete Guide

To completely reset the MongoDB cluster, stop all services, remove containers and named volumes using docker-compose down -v --rmi all --remove-orphans, then run docker-compose up -d to trigger the automatic reinitialization scripts.

The minhhungit/mongodb-cluster-docker-compose repository provides a self-healing, sharded MongoDB cluster orchestrated via Docker Compose. When testing data changes, recovering from corrupted states, or reproducing fresh environments, you must follow a specific procedure to reset and reinitialize the MongoDB cluster while ensuring all replica sets, config servers, and shard routers are properly recreated.

Why You Need to Reset the MongoDB Cluster

A sharded MongoDB cluster maintains state across multiple components: config servers store metadata, shard replica sets hold data partitions, and mongos routers handle query routing. Simply restarting containers preserves the underlying named volumes defined in docker-compose.yml, which means:

• Corrupted data files persist across restarts
• Replica set configurations remain stale
• Shard topology may reference non-existent nodes

To achieve a true clean slate, you must delete the persistent volumes that store data files for each shard, config server, and router.

Prerequisites for Reinitializing the Cluster

Before executing the reset procedure, ensure you have:

• Docker and Docker Compose installed on your host system
• Administrative privileges to remove volumes and containers
• The repository cloned locally with access to the scripts/ directory containing initialization logic
• All client applications disconnected from the mongos routers to prevent data loss warnings

Step-by-Step Procedure to Reset and Reinitialize the MongoDB Cluster

Stop the Running Stack

First, ensure no containers are actively writing to the volumes. While docker-compose down will stop services automatically, you can explicitly stop them first:

docker-compose stop

Remove Containers and Persistent Volumes

This is the critical step that distinguishes a simple restart from a complete reset. You must remove the named volumes defined under the volumes: section in docker-compose.yml (such as mongodb_cluster_shard01_a_db, mongodb_cluster_configsvr01_db, etc.).

Execute the comprehensive cleanup command:

docker-compose down -v --rmi all --remove-orphans

What this command does:

• -v removes the named volumes containing MongoDB data files, config server metadata, and shard replica set data
• --rmi all deletes the images built for the cluster components
• --remove-orphans cleans up any containers not defined in the current docker-compose.yml

Recreate the Cluster

With all persistent data erased, bring the stack back up:

docker-compose up -d

Docker Compose will recreate all containers. The entrypoint scripts located in the scripts/ directory will automatically execute:

• scripts/entrypoint-configserver.sh runs scripts/init-configserver.js to initialize the config server replica set via rs.initiate()
• scripts/entrypoint-shard01.sh (and corresponding scripts for other shards) execute scripts/init-shard01.js to initiate each shard's replica set
• scripts/entrypoint-router.sh executes scripts/init-router.js, which connects to the mongos router and calls sh.addShard() for each replica set, establishing the sharding topology

Verify the Reinitialization

Confirm that the cluster has been fully reinitialized by checking the sharding status on the router:

while true; do \
  docker exec -it router-01 bash -c "echo 'sh.status()' | mongosh --port 27017" \
  && break || sleep 2; \
done

This command polls the router-01 container until sh.status() returns successfully, indicating that the config server, shards, and router are properly connected and the cluster is ready for use.

Understanding the Auto-Initialization Scripts

The reset procedure works because the repository uses idempotent initialization scripts that run on container startup. When you delete volumes and recreate containers, these scripts execute as if for the first time:

• scripts/entrypoint-configserver.sh and scripts/init-configserver.js: Handle the config server replica set initialization defined in docker-compose.yml under the mongo-config-01 service.
• scripts/entrypoint-shard01.sh (and similar for shards 02, 03): Each executes its corresponding scripts/init-shard0X.js to initiate that shard's replica set with the proper _id and members array.
• scripts/entrypoint-router.sh and scripts/init-router.js: Connect to the router-01 service and execute sh.addShard() commands to register each shard replica set with the cluster's config servers.

These scripts rely on the environment variables and hostnames defined in docker-compose.yml, ensuring that when volumes are empty, the cluster topology is rebuilt consistently.

Summary

• Complete reset requires volume deletion: Simply stopping containers preserves data in named volumes; you must use docker-compose down -v to erase persistent MongoDB data files.
• Use the full cleanup command: docker-compose down -v --rmi all --remove-orphans ensures containers, volumes, images, and orphans are all removed.
• Automatic reinitialization: Running docker-compose up -d triggers entrypoint scripts (scripts/entrypoint-*.sh and scripts/init-*.js) that recreate config servers, shard replica sets, and router topology without manual intervention.
• Verify with sh.status(): Always confirm the cluster is operational by executing sh.status() on the router container after reinitialization.

Frequently Asked Questions

What happens if I don't delete the named volumes when resetting the cluster?

If you omit the -v flag in docker-compose down, the named volumes (such as mongodb_cluster_shard01_a_db and mongodb_cluster_configsvr01_db) persist on the host filesystem. When you run docker-compose up, the new containers mount these existing volumes containing old data files and replica set configurations, causing initialization scripts to fail or skip because they detect existing data, leaving you with a partially configured or corrupted cluster state rather than a fresh environment.

How long does the reinitialization process take?

The complete reset and reinitialization typically takes between 30 to 90 seconds, depending on your host system's I/O performance and CPU resources. The docker-compose down -v command completes in a few seconds, while docker-compose up -d requires time to pull images (if --rmi all was used), create containers, and execute the initialization scripts. The config server replica set initialization (scripts/init-configserver.js) and shard replica set initialization (scripts/init-shard0X.js) usually complete within 10-20 seconds, after which the router (scripts/init-router.js) adds shards to the cluster.

Can I reset a single shard without affecting the other shards and config servers?

While the repository's standard reset procedure targets the entire cluster, you can reset an individual shard by manually removing only that shard's specific named volumes and containers. You would need to identify the specific volume names for that shard (e.g., mongodb_cluster_shard02_a_db, mongodb_cluster_shard02_b_db, mongodb_cluster_shard02_c_db) from docker-compose.yml, run docker-compose stop for that specific service, remove those specific volumes with docker volume rm, then restart the service. However, you must then manually reinitialize the shard replica set using rs.initiate() and run sh.addShard() from the router to re-add it to the cluster topology, as the automated entrypoint scripts only run on initial container creation.

Where are the initialization scripts located and how do they work?

The initialization scripts are located in the scripts/ directory at the repository root. The shell scripts (scripts/entrypoint-configserver.sh, scripts/entrypoint-shard01.sh, scripts/entrypoint-router.sh, etc.) serve as container entrypoints that wait for MongoDB processes to become ready, then execute the corresponding JavaScript files. The JavaScript files (scripts/init-configserver.js, scripts/init-shard01.js, scripts/init-router.js) contain the actual MongoDB commands: rs.initiate() for replica set configuration, and sh.addShard() for registering shards with the config servers. These scripts execute automatically when you run docker-compose up -d after a volume reset, ensuring the cluster self-assembles without manual intervention.

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