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

> Easily reset and reinitialize your MongoDB cluster in Docker Compose. Follow this guide to stop services, remove containers, and bring your cluster back online quickly.

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

---

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

```bash
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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/docker-compose.yml) (such as `mongodb_cluster_shard01_a_db`, `mongodb_cluster_configsvr01_db`, etc.).

Execute the comprehensive cleanup command:

```bash
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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/docker-compose.yml)

### Recreate the Cluster

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

```bash
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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/entrypoint-configserver.sh) runs [`scripts/init-configserver.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/init-configserver.js) to initialize the config server replica set via `rs.initiate()`
- [`scripts/entrypoint-shard01.sh`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/entrypoint-shard01.sh) (and corresponding scripts for other shards) execute [`scripts/init-shard01.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/init-shard01.js) to initiate each shard's replica set
- [`scripts/entrypoint-router.sh`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/entrypoint-router.sh) executes [`scripts/init-router.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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:

```bash
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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/entrypoint-configserver.sh)** and **[`scripts/init-configserver.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/init-configserver.js)**: Handle the config server replica set initialization defined in [`docker-compose.yml`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/docker-compose.yml) under the `mongo-config-01` service.
- **[`scripts/entrypoint-shard01.sh`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/entrypoint-shard01.sh)** (and similar for shards 02, 03): Each executes its corresponding **[`scripts/init-shard0X.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/init-shard0X.js)** to initiate that shard's replica set with the proper `_id` and members array.
- **[`scripts/entrypoint-router.sh`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/entrypoint-router.sh)** and **[`scripts/init-router.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/init-configserver.js)) and shard replica set initialization ([`scripts/init-shard0X.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/init-shard0X.js)) usually complete within 10-20 seconds, after which the router ([`scripts/init-router.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/entrypoint-configserver.sh), [`scripts/entrypoint-shard01.sh`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/entrypoint-shard01.sh), [`scripts/entrypoint-router.sh`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/init-configserver.js), [`scripts/init-shard01.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/init-shard01.js), [`scripts/init-router.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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.