Docker Compose MongoDB Replica Set: Complete Reference

TL;DR

• Bottom line: A 3-node MongoDB replica set in Docker Compose requires matching --replSet names, a shared keyfile for auth, a custom bridge network for DNS resolution, and a one-time rs.initiate() call to bootstrap the cluster.
• Key tool/command: mongosh --eval "rs.initiate({_id:'rs0', members:[{_id:0,host:'mongo1:27017'},{_id:1,host:'mongo2:27017'},{_id:2,host:'mongo3:27017'}]})"
• Watch out for: Hostnames in rs.initiate() members must be resolvable by both the containers AND your application -- using localhost inside containers breaks cross-node communication.
• Works with: MongoDB 7.0+, 8.0+; Docker Compose V2 (the docker compose plugin); Docker Engine 24+.

Constraints

• Replica set names in --replSet flag MUST match the _id in rs.initiate() -- mismatch causes silent failure
• Keyfile permissions MUST be 400 and owned by mongodb user (UID 999) inside the container -- MongoDB refuses to start otherwise
• NEVER run a production replica set without authentication (keyFile or x509) -- any network-accessible mongod without auth is fully open
• Use odd number of voting members (1, 3, 5, 7 max) to avoid split-brain during elections
• Container hostnames in rs.initiate() members MUST be resolvable by all replica set members AND by connecting clients

Quick Reference

Service Configuration

Replica Set Member Roles

Connection String Formats

Decision Tree

START: What is your use case?
├── Local development (need transactions/change streams)?
│   ├── YES → Single-node replica set (1 member, simplest setup)
│   └── NO ↓
├── Development/staging with HA testing?
│   ├── YES → 3-node replica set (primary + 2 secondaries)
│   └── NO ↓
├── Production with budget constraints?
│   ├── YES → 2 data nodes + 1 arbiter (saves storage, still has quorum)
│   └── NO ↓
├── Production with full redundancy?
│   ├── YES → 3-node replica set with keyfile auth + named volumes + resource limits
│   └── NO ↓
├── Need read scaling across regions?
│   ├── YES → 5 or 7 members with priorities + readPreference=secondary
│   └── NO ↓
└── DEFAULT → 3-node replica set with keyfile authentication

Step-by-Step Guide

1. Generate the keyfile for internal authentication

The keyfile is used for inter-node authentication within the replica set. All members must share the same keyfile. [src1]

# Generate a random 756-byte base64-encoded key
openssl rand -base64 756 > ./keyfile

# Set restrictive permissions (MongoDB requires 400)
chmod 400 ./keyfile

# On Linux, change ownership to match the MongoDB container user (UID 999)
sudo chown 999:999 ./keyfile

Verify: ls -la ./keyfile → expected: -r-------- 1 999 999 1024 ... keyfile

2. Create the Docker Compose file

Define three MongoDB services on a shared network with the keyfile mounted read-only. [src2] [src4]

Full docker-compose.yml: see markdown source for the complete 3-node configuration with healthchecks, named volumes, and an init container.

Verify: docker compose config → should output valid YAML with no errors.

3. Create the replica set initialization script

This script connects to the primary candidate and runs rs.initiate() with the member list. [src1] [src5]

#!/bin/bash
# init-replica.sh
echo "Waiting for MongoDB nodes..."
sleep 10
mongosh --host mongo1:27017 -u admin -p "${MONGO_PASSWORD:-changeme}" \
  --authenticationDatabase admin --eval '
  rs.initiate({
    _id: "rs0",
    members: [
      { _id: 0, host: "mongo1:27017", priority: 3 },
      { _id: 1, host: "mongo2:27017", priority: 2 },
      { _id: 2, host: "mongo3:27017", priority: 1 }
    ]
  });
'

Verify: docker logs mongo-init → expected: member list with PRIMARY and SECONDARY states.

4. Start the cluster and verify

Bring up all services and check the replica set status. [src3]

# Start all services
docker compose up -d

# Check init container logs
docker compose logs -f mongo-init

# Connect to primary and verify
docker exec -it mongo1 mongosh -u admin -p changeme \
  --authenticationDatabase admin --eval "rs.status()"

Verify: rs.status().members should show 3 members -- one PRIMARY and two SECONDARY.

5. Create application database and user

After the replica set is running, create a dedicated database user for your application. [src1]

use admin;
db.createUser({
  user: "appuser",
  pwd: "appsecret",
  roles: [
    { role: "readWrite", db: "myapp" },
    { role: "readWrite", db: "myapp_test" }
  ]
});

Verify: mongosh -u appuser -p appsecret --authenticationDatabase admin myapp --eval "db.test.insertOne({ok:1})" → expected: { acknowledged: true }

6. Test write concern and read preference

Verify replication by writing with majority write concern and reading from secondaries. [src7]

db.test.insertOne(
  { msg: "replicated", ts: new Date() },
  { writeConcern: { w: "majority", wtimeout: 5000 } }
);
db.getMongo().setReadPref("secondary");
db.test.find();

Verify: Document appears on secondary reads; rs.printReplicationInfo() shows replication lag < 1 second.

Code Examples

Single-Node Replica Set (Minimal Development Setup)

# docker-compose.yml -- Single-node replica set for local dev
services:
  mongodb:
    image: mongo:7.0
    command: ["--replSet", "rs0", "--bind_ip_all"]
    ports:
      - "27017:27017"
    volumes:
      - mongo-data:/data/db
    healthcheck:
      test: >
        mongosh --eval "try{rs.status().ok}catch(e){rs.initiate({_id:'rs0',members:[{_id:0,host:'localhost:27017'}]}).ok}"
      interval: 10s
      timeout: 10s
      retries: 5
volumes:
  mongo-data:

Node.js: Connection with Retry Logic

const { MongoClient } = require('mongodb');  // ^6.0.0

const uri = 'mongodb://admin:changeme@mongo1:27017,mongo2:27017,mongo3:27017/?replicaSet=rs0&authSource=admin';

const client = new MongoClient(uri, {
  readPreference: 'secondaryPreferred',
  w: 'majority',
  retryWrites: true,
  retryReads: true,
  serverSelectionTimeoutMS: 5000,
});

await client.connect();
const status = await client.db('admin').command({ replSetGetStatus: 1 });
console.log('Connected to replica set:', status.set);

Python: Connection with PyMongo

from pymongo import MongoClient  # pymongo >= 4.6.0

uri = (
    "mongodb://admin:changeme@mongo1:27017,mongo2:27017,mongo3:27017/"
    "?replicaSet=rs0&authSource=admin"
    "&readPreference=secondaryPreferred&w=majority"
)

client = MongoClient(uri, serverSelectionTimeoutMS=5000)
status = client.admin.command("replSetGetStatus")
print(f"Connected to: {status['set']}")

With Arbiter Node (Budget HA)

2 data nodes + 1 arbiter: saves storage costs while maintaining quorum for elections. See markdown source for complete docker-compose.yml with arbiterOnly: true in rs.initiate().

Anti-Patterns

Wrong: Using localhost in replica set member hostnames

# BAD -- localhost only resolves within a single container
command: ["--replSet", "rs0", "--bind_ip", "localhost"]
# rs.initiate with localhost: members cannot reach each other

Correct: Use container hostnames on a shared network

# GOOD -- container hostnames resolve via Docker DNS
command: ["--replSet", "rs0", "--bind_ip_all"]
# members: [{host: "mongo1:27017"}, {host: "mongo2:27017"}, ...]

Wrong: Keyfile with permissive permissions

# BAD -- MongoDB refuses to start
chmod 644 ./keyfile
# Error: "permissions on /etc/mongo-keyfile are too open"

Correct: Restrictive keyfile permissions with correct ownership

# GOOD -- only owner can read, owned by mongodb user (UID 999)
chmod 400 ./keyfile
sudo chown 999:999 ./keyfile

Wrong: Mismatched replica set names

# BAD -- replSet name in command does not match rs.initiate _id
command: ["--replSet", "myRS"]
# Then: rs.initiate({ _id: "rs0", ... }) -- silent failure

Correct: Consistent replica set name everywhere

# GOOD -- same name in command flag and rs.initiate
command: ["--replSet", "rs0"]
# rs.initiate({ _id: "rs0", ... })

Wrong: No healthcheck or init container

# BAD -- no mechanism to initialize replica set automatically
services:
  mongo1:
    image: mongo:7.0
    command: ["--replSet", "rs0"]
    # Requires manual mongosh after every restart

Correct: Healthcheck-based or init container initialization

# GOOD -- healthcheck auto-initializes on first run
healthcheck:
  test: >
    mongosh --eval "try{rs.status().ok}catch(e){rs.initiate({_id:'rs0',members:[{_id:0,host:'mongo1:27017'}]}).ok}"
  interval: 10s

Wrong: Even number of voting members

// BAD -- 2 voting members cannot elect if one fails
rs.initiate({
  _id: "rs0",
  members: [
    { _id: 0, host: "mongo1:27017" },
    { _id: 1, host: "mongo2:27017" }
  ]
});

Correct: Odd number of voting members

// GOOD -- 3 members: majority is 2, survives 1 failure
rs.initiate({
  _id: "rs0",
  members: [
    { _id: 0, host: "mongo1:27017" },
    { _id: 1, host: "mongo2:27017" },
    { _id: 2, host: "mongo3:27017" }
  ]
});

Common Pitfalls

• Keyfile ownership inside container: The mongo Docker image runs as UID 999. If the keyfile is owned by root, MongoDB cannot read it. Fix: sudo chown 999:999 ./keyfile. [src1]
• MONGO_INITDB vars only work on first run: MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD are only processed when /data/db is empty. Fix: docker compose down -v to re-initialize. [src2]
• Host cannot resolve container hostnames: Applications on the host cannot resolve mongo1. Fix: Add entries to /etc/hosts or use localhost:27017,localhost:27018,localhost:27019. [src5]
• rs.initiate() fails during startup: MongoDB needs time to accept connections. Fix: Use depends_on with condition: service_healthy or add sleep 10. [src4]
• Election timeout during failover: Default electionTimeoutMillis is 10 seconds. Writes fail during this window. Fix: Implement retry logic in your application. [src7]
• Bind IP not set to all interfaces: Default mongod binds to localhost only. Fix: Always use --bind_ip_all. [src3]
• Missing write concern for critical data: Default w:1 acknowledges primary only. Fix: Use w: "majority" for important writes. [src7]
• Windows Docker keyfile permissions: Docker on Windows cannot enforce Linux file permissions via volume mounts. Fix: Copy keyfile into a custom image or generate via entrypoint. [src2]

Diagnostic Commands

# Check replica set status
docker exec -it mongo1 mongosh -u admin -p changeme --authenticationDatabase admin --eval "rs.status()"

# Show replica set configuration
docker exec -it mongo1 mongosh -u admin -p changeme --authenticationDatabase admin --eval "rs.conf()"

# Check replication lag
docker exec -it mongo1 mongosh -u admin -p changeme --authenticationDatabase admin --eval "rs.printReplicationInfo()"

# Identify primary node
docker exec -it mongo1 mongosh -u admin -p changeme --authenticationDatabase admin --eval "rs.isMaster().primary"

# Verify all members are healthy
docker exec -it mongo1 mongosh -u admin -p changeme --authenticationDatabase admin --eval "rs.status().members.map(m => ({name: m.name, state: m.stateStr, health: m.health}))"

# Test connection string from host
mongosh "mongodb://admin:changeme@localhost:27017,localhost:27018,localhost:27019/?replicaSet=rs0&authSource=admin" --eval "db.runCommand({ping:1})"

# Check container health
docker compose ps

# Force primary step-down (failover testing)
docker exec -it mongo1 mongosh -u admin -p changeme --authenticationDatabase admin --eval "rs.stepDown(60)"

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• Docker volumes persist data across restarts, but docker compose down -v deletes all data -- never use -v in production without backups
• MONGO_INITDB_ROOT_USERNAME/PASSWORD only initialize on first run when /data/db is empty; changing them after has no effect
• On macOS and Windows, Docker Desktop uses a Linux VM, so volume performance is slower than native Linux; use named volumes instead of bind mounts for /data/db
• Replica set elections take 10-12 seconds by default; your application must handle write failures during this window with retry logic
• The official mongo Docker image runs as root but switches to UID 999 for mongod; file permissions must account for this
• In Docker Swarm or Kubernetes, container hostnames and DNS work differently -- this guide is for single-host Docker Compose deployments