DEV Community: Selim

MongoDB Replica Set Compose OS independent

Selim — Tue, 12 Aug 2025 08:58:07 +0000

Quick start on how to containerize MongoDB Replica Set on your machine.

In about 5 minutes, the 3-Node Replica Set will be running on your machine without any prior experience with container platforms or databases.

What is the purpose of a Replica Set on a single machine?

Initializing a Replica Set on a single machine is necessary to enable certain MongoDB features such as Changestreams for real-time applications and Transactions for ACID-compliant database operations.

Prerequisites

Editor of your choice, I will be using Visual Studio Code
Container platform with Compose support, I will demonstrate using both Docker and Podman

Getting started

Your directory should look something like this:

project
├── compose.yml
└── .env

Copy and paste the compose.yml:

services:
  mongo_1:
    container_name: mongo_1
    hostname: mongo_1
    image: mongo:latest
    command: >
      bash -c "
        echo 'Starting without auth for initial setup...'
        if [ ! -f /shared/setup_completed ]; then
          echo 'Running without auth for replica set initialization'
          mongod --replSet rs0 --bind_ip_all --port 27017 &
          while [ ! -f /shared/setup_completed ]; do
            sleep 1
          done
          echo 'Setup completed, restarting with auth...'
          pkill mongod
          sleep 2
        fi
        echo 'Starting with auth...'
        mongod --replSet rs0 --bind_ip_all --port 27017 --keyFile /shared/mongodb-keyfile --auth
      "
    volumes:
      - mongo_1_data:/data/db
      - mongo_1_config:/data/configdb
      - mongo_keyfile:/shared
    restart: always
    networks:
      - mongo_network
    ports:
      - "27017:27017"

  mongo_2:
    container_name: mongo_2
    hostname: mongo_2
    image: mongo:latest
    command: >
      bash -c "
        echo 'Starting without auth for initial setup...'
        if [ ! -f /shared/setup_completed ]; then
          echo 'Running without auth for replica set initialization'
          mongod --replSet rs0 --bind_ip_all --port 27018 &
          while [ ! -f /shared/setup_completed ]; do
            sleep 1
          done
          echo 'Setup completed, restarting with auth...'
          pkill mongod
          sleep 2
        fi
        echo 'Starting with auth...'
        mongod --replSet rs0 --bind_ip_all --port 27018 --keyFile /shared/mongodb-keyfile --auth
      "
    volumes:
      - mongo_2_data:/data/db
      - mongo_2_config:/data/configdb
      - mongo_keyfile:/shared
    restart: always
    networks:
      - mongo_network
    ports:
      - "27018:27018"

  mongo_3:
    container_name: mongo_3
    hostname: mongo_3
    image: mongo:latest
    command: >
      bash -c "
        echo 'Starting without auth for initial setup...'
        if [ ! -f /shared/setup_completed ]; then
          echo 'Running without auth for replica set initialization'
          mongod --replSet rs0 --bind_ip_all --port 27019 &
          while [ ! -f /shared/setup_completed ]; do
            sleep 1
          done
          echo 'Setup completed, restarting with auth...'
          pkill mongod
          sleep 2
        fi
        echo 'Starting with auth...'
        mongod --replSet rs0 --bind_ip_all --port 27019 --keyFile /shared/mongodb-keyfile --auth
      "
    volumes:
      - mongo_3_data:/data/db
      - mongo_3_config:/data/configdb
      - mongo_keyfile:/shared
    restart: always
    networks:
      - mongo_network
    ports:
      - "27019:27019"

  mongo_setup:
    container_name: mongo_setup
    image: mongo:latest
    environment:
      - MONGO_INITDB_ROOT_USERNAME=${MONGO_INITDB_ROOT_USERNAME}
      - MONGO_INITDB_ROOT_PASSWORD=${MONGO_INITDB_ROOT_PASSWORD}
    command: >
      bash -c "
        if [ -f /shared/setup_completed ]; then
          echo 'Cluster setup already completed, skipping'
          exit 0
        fi
        echo 'Generating keyfile...' &&
        if [ ! -f /shared/mongodb-keyfile ]; then
          openssl rand -base64 756 > /shared/mongodb-keyfile &&
          chmod 600 /shared/mongodb-keyfile &&
          chown 999:999 /shared/mongodb-keyfile &&
          echo 'Keyfile generated successfully'
        else
          echo 'Keyfile already exists, skipping generation'
        fi &&
        echo 'Waiting for node startup...' &&
        sleep 5 &&
        echo 'Initializing replica set...' &&
        mongosh --host mongo_1 --port 27017 --eval '
          try {
            rs.initiate({
              _id: "rs0",
              members: [
                {_id: 0, host: "mongo_1:27017", priority: 1},
                {_id: 1, host: "mongo_2:27018", priority: 0.5},
                {_id: 2, host: "mongo_3:27019", priority: 0.5}
              ]
            });
            print("Replica set initialized successfully");
          } catch (e) {
            print("Replica set initialization failed or already exists: " + e);
          }
        ' &&
        echo 'Waiting for primary election...' &&
        sleep 20 &&
        echo 'Creating admin user...' &&
        mongosh --host mongo_1 --port 27017 --eval '
          try {
            db = db.getSiblingDB("admin");
            db.createUser({
              user: "'$$MONGO_INITDB_ROOT_USERNAME'",
              pwd: "'$$MONGO_INITDB_ROOT_PASSWORD'",
              roles: [{role: "root", db: "admin"}]
            });
            print("Admin user created successfully");
          } catch (e) {
            print("User creation failed: " + e);
            throw e;
          }
        ' &&
        touch /shared/setup_completed &&
        echo 'Cluster setup completed successfully!'
      "
    volumes:
      - mongo_setup_data:/data/db
      - mongo_setup_config:/data/configdb
      - mongo_keyfile:/shared
    restart: "no"
    networks:
      - mongo_network

  mongo_express:
    container_name: mongo_express
    image: mongo-express:latest
    environment:
      - ME_CONFIG_MONGODB_ADMINUSERNAME=${MONGO_INITDB_ROOT_USERNAME}
      - ME_CONFIG_MONGODB_ADMINPASSWORD=${MONGO_INITDB_ROOT_PASSWORD}
      - ME_CONFIG_MONGODB_URL=mongodb://${MONGO_INITDB_ROOT_USERNAME}:${MONGO_INITDB_ROOT_PASSWORD}@mongo_1:27017,mongo_2:27018,mongo_3:27019/?replicaSet=rs0
      - ME_CONFIG_BASICAUTH_USERNAME=${MONGO_INITDB_ROOT_USERNAME}
      - ME_CONFIG_BASICAUTH_PASSWORD=${MONGO_INITDB_ROOT_PASSWORD}
    restart: always
    networks:
      - mongo_network
    ports:
      - "8081:8081"

volumes:
  mongo_1_data:
  mongo_2_data:
  mongo_3_data:
  mongo_setup_data:
  mongo_1_config:
  mongo_2_config:
  mongo_3_config:
  mongo_setup_config:
  mongo_keyfile:

networks:
  mongo_network:
    driver: bridge

Set your admin username and password in .env:

MONGO_INITDB_ROOT_USERNAME="root"
MONGO_INITDB_ROOT_PASSWORD="pass"

Run the Compose setup in your project directory
Docker:

docker compose up -d

Podman:

podman compose up -d

Wait about 45 seconds, then run the setup logs
Docker:

docker logs mongo_setup

Podman:

podman logs mongo_setup

If everything went right the output should look like this:

Generating keyfile...
Keyfile generated successfully
Waiting for node startup...
Initializing replica set...
Replica set initialized successfully
Waiting for primary election...
Creating admin user...
Admin user created successfully
Cluster setup completed successfully!

The final step is to map hosts 127.0.0.1 to mongo_1, mongo_2 and mongo_3
Windows Powershell:

Start-Process powershell.exe -Verb RunAs -ArgumentList '-NoProfile', '-Command', 'Add-Content -Path "C:\Windows\System32\drivers\etc\hosts" -Value "`n127.0.0.1   mongo_1 mongo_2 mongo_3"'

Mac/Linux Zsh/Bash:

echo "127.0.0.1   mongo_1 mongo_2 mongo_3" | sudo tee -a /etc/hosts > /dev/null

Access your MongoDB Replica Set

Open your browser on http://localhost:8081/ and login with your .env credentials
To connect via MongoDB Compass or drivers, use this connection string to enable Replica Set connectivity with automatic failover. (Be sure to replace "root" and "pass" with your .env credentials):
mongodb://root:pass@127.0.0.1:27017,127.0.0.1:27018,127.0.0.1:27019/?replicaSet=rs0

Local MongoDB Replica Set Cluster for Real-Time Container Apps (with Mongo Express)

Selim — Sat, 09 Aug 2025 18:49:23 +0000

Run a full 3-node MongoDB replica set locally for real-time containerized applications, with authentication, failover, and Mongo Express — all in one compose.yml.

If you’re developing containerized applications that need real-time MongoDB features like Change Streams, you’ll want a local replica set.

This guide shows you how to run a 3-node MongoDB cluster with authentication, automatic failover, and a built-in web interface — all in one compose.yml file.

I built this setup primarily for Podman, but it works with most container platforms, including Docker, with no changes.

You’ll get:

A 3-node MongoDB replica set — perfect for local development & real-time features
Keyfile-based authentication
Automatic replica set initialization
A configurable root admin user via .env
Mongo Express for browser-based DB management
Ready-to-use connection strings for primary and secondary nodes
Works with Docker & Podman

Why Use a Replica Set Locally?

Running a MongoDB replica set locally lets you:

Test high availability scenarios — simulate node failures
Work with real-time features like Change Streams
Develop apps that mirror production environments
Explore read preference configurations with primary and secondary nodes

The Setup

The cluster is defined in a single compose.yml that includes:

keyfile-generator – creates a secure keyfile for internal node authentication
mongo1, mongo2, mongo3 – the three replica set members
mongo-express – a web-based MongoDB admin interface

1 `.env` File

Create a .env file in the same directory:

MONGO_INITDB_ROOT_USERNAME=root
MONGO_INITDB_ROOT_PASSWORD=pass

Change these values to your preferred admin credentials.

2 `compose.yml`

Here’s the full configuration:

services:
  keyfile-generator:
    image: alpine:latest
    restart: "no"
    command: >
      sh -c "
        apk add --no-cache openssl &&
        if [ ! -f /data/keyfile ]; then
          openssl rand -base64 756 > /data/keyfile &&
          chmod 400 /data/keyfile;
        fi
      "
    volumes:
      - keyfile_data:/data

  mongo1:
    image: mongo:latest
    container_name: mongo1
    depends_on:
      - keyfile-generator
    restart: unless-stopped
    ports:
      - 27017:27017
    networks:
      - mongoCluster
    volumes:
      - mongo1_data:/data/db
      - mongo1_config:/data/configdb
      - keyfile_data:/etc/mongo-keyfile
    environment:
      - MONGO_INITDB_ROOT_USERNAME=${MONGO_INITDB_ROOT_USERNAME}
      - MONGO_INITDB_ROOT_PASSWORD=${MONGO_INITDB_ROOT_PASSWORD}
    command: >
      bash -c '
        echo "Starting MongoDB setup..."
        while [ ! -f /etc/mongo-keyfile/keyfile ]; do
          echo "Waiting for keyfile..."
          sleep 2
        done
        chmod 400 /etc/mongo-keyfile/keyfile
        mongod --replSet rs0 --bind_ip_all --keyFile /etc/mongo-keyfile/keyfile --fork --logpath /var/log/mongod.log
        for i in {1..30}; do
          if mongosh --quiet --eval "db.runCommand({ping: 1})" > /dev/null 2>&1; then
            break
          fi
          sleep 2
        done
        if ! mongosh --quiet --eval "rs.status()" > /dev/null 2>&1; then
          mongosh --eval "
            rs.initiate({
              _id: \"rs0\",
              members: [
                { _id: 0, host: \"mongo1:27017\", priority: 2 },
                { _id: 1, host: \"mongo2:27017\", priority: 1 },
                { _id: 2, host: \"mongo3:27017\", priority: 1 }
              ]
            })
          "
        fi
        for i in {1..60}; do
          if mongosh --quiet --eval "db.hello().isWritablePrimary" 2>/dev/null | grep -q true; then
            mongosh admin --quiet --eval "db.createUser({user:\"${MONGO_INITDB_ROOT_USERNAME}\",pwd:\"${MONGO_INITDB_ROOT_PASSWORD}\",roles:[{role:\"root\",db:\"admin\"}]})"
            break
          fi
          sleep 2
        done
        mongod --shutdown
        sleep 3
        exec mongod --replSet rs0 --bind_ip_all --auth --keyFile /etc/mongo-keyfile/keyfile
      '

  mongo2:
    image: mongo:latest
    container_name: mongo2
    depends_on:
      - keyfile-generator
    restart: unless-stopped
    ports:
      - 27018:27017
    networks:
      - mongoCluster
    volumes:
      - mongo2_data:/data/db
      - mongo2_config:/data/configdb
      - keyfile_data:/etc/mongo-keyfile
    command: >
      bash -c "
        chmod 400 /etc/mongo-keyfile/keyfile &&
        exec mongod --replSet rs0 --bind_ip_all --auth --keyFile /etc/mongo-keyfile/keyfile
      "

  mongo3:
    image: mongo:latest
    container_name: mongo3
    depends_on:
      - keyfile-generator
    restart: unless-stopped
    ports:
      - 27019:27017
    networks:
      - mongoCluster
    volumes:
      - mongo3_data:/data/db
      - mongo3_config:/data/configdb
      - keyfile_data:/etc/mongo-keyfile
    command: >
      bash -c "
        chmod 400 /etc/mongo-keyfile/keyfile &&
        exec mongod --replSet rs0 --bind_ip_all --auth --keyFile /etc/mongo-keyfile/keyfile
      "

  mongo-express:
    image: mongo-express:latest
    container_name: mongo-express
    depends_on:
      - mongo1
      - mongo2
      - mongo3
    restart: unless-stopped
    ports:
      - 8081:8081
    networks:
      - mongoCluster
    environment:
      - ME_CONFIG_MONGODB_ADMINUSERNAME=${MONGO_INITDB_ROOT_USERNAME}
      - ME_CONFIG_MONGODB_ADMINPASSWORD=${MONGO_INITDB_ROOT_PASSWORD}
      - ME_CONFIG_MONGODB_URL=mongodb://${MONGO_INITDB_ROOT_USERNAME}:${MONGO_INITDB_ROOT_PASSWORD}@mongo1:27017,mongo2:27017,mongo3:27017/?replicaSet=rs0
      - ME_CONFIG_BASICAUTH_USERNAME=${MONGO_INITDB_ROOT_USERNAME}
      - ME_CONFIG_BASICAUTH_PASSWORD=${MONGO_INITDB_ROOT_PASSWORD}

networks:
  mongoCluster:
    driver: bridge

volumes:
  mongo1_data:
  mongo1_config:
  mongo2_data:
  mongo2_config:
  mongo3_data:
  mongo3_config:
  keyfile_data:

3 Starting the Cluster

With Podman:

podman compose up -d

With Docker:

docker compose up -d

On first run:

A secure keyfile is generated
The replica set (rs0) is initialized
A root admin user is created
MongoDB restarts in auth mode
After the first Bootup is completed you may delete the keyfile-generator Container

Connecting to the Cluster

e.g. MongoDB Compass

Direct node connections:

Primary: mongodb://root:pass@localhost:27017/?authSource=admin&directConnection=true
Secondary 1: mongodb://root:pass@localhost:27018/?authSource=admin&directConnection=true
Secondary 2: mongodb://root:pass@localhost:27019/?authSource=admin&directConnection=true

(Replace root / pass if changed in .env)

Mongo Express UI

Access Mongo Express at:

http://localhost:8081

Next Steps

Add TLS/SSL for encrypted connections
Implement Failover Logic between direct node connection strings in your app
Implement Change Streams in your app
Simulate node failures to test high availability