How Data Persistence is Ensured Across MongoDB Container Restarts

Data persistence across MongoDB container restarts in the minhhungit/mongodb-cluster-docker-compose repository is achieved through Docker named volumes mounted at /data/db and /data/configdb, combined with restart: always policies that automatically recover services after crashes or host reboots.

The minhhungit/mongodb-cluster-docker-compose project orchestrates a complete sharded MongoDB cluster using Docker Compose. When running distributed databases in containers, ensuring data persistence across MongoDB container restarts is critical to prevent data loss during maintenance, crashes, or system updates.

Docker Named Volumes as the Persistence Layer

The architecture relies on Docker named volumes to store data outside the container's writable layer. This separation ensures that database files survive container destruction and recreation.

Volume Mount Points in MongoDB Containers

Each service in the cluster mounts two specific paths to dedicated named volumes:

• /data/db – Stores the primary MongoDB data files (WiredTiger storage engine files, collections, and indexes)
• /data/configdb – Stores replica set configuration and metadata

In docker-compose.yml, the router service (router01) declares these mounts as follows:

router01:
  image: mongo:latest
  container_name: router-01
  ports:
    - "27117:27017"
  restart: always
  volumes:
    - ./scripts:/scripts
    - mongodb_cluster_router01_db:/data/db
    - mongodb_cluster_router01_config:/data/configdb
  entrypoint: ["/scripts/entrypoint-route.sh"]

Named Volume Definitions

The top-level volumes section in docker-compose.yml declares persistent storage for every cluster component. Docker manages these volumes in /var/lib/docker/volumes/ on the host:

volumes:
  mongodb_cluster_router01_db:
  mongodb_cluster_router01_config:
  mongodb_cluster_configsvr01_db:
  mongodb_cluster_configsvr01_config:
  mongodb_cluster_configsvr02_db:
  mongodb_cluster_configsvr02_config:
  # ... additional volumes for config servers and shard members

Automatic Recovery with Restart Policies

Beyond volume persistence, the repository ensures high availability through aggressive restart policies. Every service includes restart: always, which instructs Docker to restart containers automatically after crashes, host reboots, or Docker daemon restarts.

This policy works in conjunction with the named volumes: when a container restarts, it reattaches the same volumes at /data/db and /data/configdb, immediately restoring access to all existing databases, collections, and shard configurations.

Managing Container Lifecycle Without Data Loss

Understanding the distinction between stopping and destroying containers is essential for maintaining data persistence across MongoDB container restarts.

Safe Stop and Start Operations

To temporarily stop the cluster without losing data, use:

# Stop all containers (data persists in named volumes)

docker-compose stop

# Restart the cluster with all data intact

docker-compose start

Dangerous Operations That Erase Data

Removing containers with the -v flag destroys the named volumes and permanently deletes all MongoDB data:

# WARNING: This deletes all persistent volumes and data

docker-compose down -v

To reset the cluster completely while preserving the ability to start fresh, use down without the -v flag, then manually remove volumes only when intentional:

# Stop and remove containers, but keep volumes (safe)

docker-compose down

# Only remove volumes when you explicitly want data loss

docker volume rm mongodb_cluster_router01_db

Summary

• Docker named volumes mounted at /data/db and /data/configdb ensure data persistence across MongoDB container restarts by storing files on the host filesystem outside container layers.
• restart: always policies automatically recover services after crashes or host reboots, reattaching existing volumes to restore data access immediately.
• docker-compose stop and docker-compose start safely pause and resume the cluster without data loss, while docker-compose down -v permanently destroys all volumes and data.
• The minhhungit/mongodb-cluster-docker-compose repository defines these volumes in docker-compose.yml for every router, config server, and shard member in the cluster.

Frequently Asked Questions

Where is MongoDB data physically stored when using named volumes?

Docker stores named volumes in /var/lib/docker/volumes/ on the host filesystem, with each volume maintaining its own directory structure. When the minhhungit/mongodb-cluster-docker-compose project mounts mongodb_cluster_router01_db to /data/db, the actual WiredTiger data files reside on the host at /var/lib/docker/volumes/mongodb_cluster_router01_db/_data/, ensuring they persist independently of container state.

Will data persist if I run docker-compose down?

Yes, running docker-compose down without the -v flag preserves all named volumes and their data. This command stops and removes containers, networks, and any anonymous volumes, but explicitly defined named volumes like mongodb_cluster_shard01_a_db remain intact on the host. You can safely run docker-compose up afterward to recreate containers with all previous data immediately available.

How do I completely reset the MongoDB cluster and delete all data?

To permanently erase all data and start with a fresh cluster, you must remove the named volumes explicitly. Execute docker-compose down -v to stop containers and delete all associated named volumes defined in docker-compose.yml. Alternatively, after running docker-compose down, manually remove specific volumes with docker volume rm mongodb_cluster_router01_db and similar commands for each service. This action is irreversible and destroys all databases, collections, and shard configurations.

Does the restart policy affect data persistence?

The restart: always policy does not directly create data persistence, but it ensures continuous access to persisted data across MongoDB container restarts. When a container crashes or the host reboots, Docker automatically restarts the container and reattaches the existing named volumes at /data/db and /data/configdb. Without this policy, containers would remain stopped after failures, requiring manual intervention to restore service, though the data would still remain safe in the named volumes on the host filesystem.

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