How Router Ports Are Mapped and Exposed for External Access in MongoDB Cluster Docker Compose

Router ports are mapped using the HOST:CONTAINER syntax in Docker Compose, exposing internal MongoDB port 27017 on distinct host ports (27117 and 27118) to enable external client connections without port conflicts.

The minhhungit/mongodb-cluster-docker-compose repository demonstrates how to configure mongos router containers for external access in a sharded MongoDB cluster. Understanding how router ports are mapped and exposed for external access is essential for connecting client applications to the cluster from outside the Docker network.

Default Single Router Configuration

In the base configuration file, a single router container exposes MongoDB traffic on a non-standard host port to avoid conflicts with local MongoDB instances.

docker-compose.yml Router Definition

The router01 service in [docker-compose.yml](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/master/docker-compose.yml) maps port 27117 on the host to port 27017 inside the container:

router01:
  image: mongo:latest
  container_name: router-01
  ports:
    - "27117:27017"   # host 27117 → container 27017

  restart: always
  volumes:
    - ./scripts:/scripts
    - mongodb_cluster_router01_db:/data/db
    - mongodb_cluster_router01_config:/data/configdb
  entrypoint: ["/scripts/entrypoint-route.sh"]

This configuration ensures the mongos process running on the standard MongoDB port inside the container is accessible externally via localhost:27117.

Key-File Authentication with Multiple Routers

The authentication-enabled variant demonstrates how to expose multiple router instances for high-availability scenarios, assigning a unique host port to each router container.

with-keyfile-auth/docker-compose.yml Configuration

In [with-keyfile-auth/docker-compose.yml](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/master/with-keyfile-auth/docker-compose.yml), two routers are defined with sequential host port assignments:

Router 01 (Port 27117):

router01:
  build:
    context: mongodb-build
  image: jin-mongo:6.0.2
  container_name: router-01
  command: mongos --port 27017 --configdb rs-config-server/configsvr01:27017,configsvr02:27017,configsvr03:27017 --bind_ip_all --keyFile /data/mongodb-keyfile
  ports:
    - 27117:27017   # first router exposed on 27117

Router 02 (Port 27118):

router02:
  build:
    context: mongodb-build
  image: jin-mongo:6.0.2
  container_name: router-02
  command: mongos --port 27017 --configdb rs-config-server/configsvr01:27017,configsvr02:27017,configsvr03:27017 --bind_ip_all --keyFile /data/mongodb-keyfile
  ports:
    - 27118:27017   # second router exposed on 27118

This dual-router setup allows client applications to connect to either localhost:27117 or localhost:27118, providing failover capabilities during rolling updates or container restarts.

How Port Mapping Enables External Access

The Docker Compose ports directive uses the HOST:CONTAINER format to bridge the internal container network with the host machine's network interface.

Port Isolation Strategy

Each router container internally runs the mongos process on port 27017, the standard MongoDB wire protocol port. However, binding this directly to the host's 27017 would conflict with any locally running MongoDB instance. The repository solves this by:

1. Mapping non-standard host ports (27117, 27118) to the standard container port (27017)
2. Avoiding port collisions with existing MongoDB installations on the development machine
3. Enabling multiple routers to run simultaneously by assigning unique host ports to each instance

Network Flow

When a client connects to mongodb://localhost:27117, Docker forwards the traffic to the router01 container's port 27017. The mongos process then routes the query to the appropriate shard based on the cluster's metadata stored in the config servers.

Connecting to Exposed Router Ports

Once the cluster is running, verify port exposure and connect using standard MongoDB clients.

Verify Port Mapping

Check that the host ports are correctly bound to the containers:

docker ps --filter "name=router-0"

Expected output showing port forwarding:

CONTAINER ID   IMAGE          COMMAND                  PORTS                      NAMES
abc123         mongo:latest   "docker-entrypoint.s…"   0.0.0.0:27117->27017/tcp   router-01
def456         jin-mongo:6.0.2 "docker-entrypoint.s…"  0.0.0.0:27118->27017/tcp   router-02

Client Connection Examples

Connect to the default single-router configuration:

mongo --host localhost --port 27117

Connect to the second router in the authentication-enabled cluster:

mongo --host localhost --port 27118 --username admin --password secret --authenticationDatabase admin

Using a connection string in application code:

from pymongo import MongoClient

# Connect to the exposed router port

client = MongoClient("mongodb://localhost:27117")
db = client.mydatabase
collection = db.mycollection

# Operations are routed to appropriate shards automatically

result = collection.find_one({"_id": 1})

Summary

• Port mapping syntax: The repository uses HOST:CONTAINER format (e.g., 27117:27017) in the ports directive of Docker Compose files.
• Default configuration: Single router (router01) exposes host port 27117 mapped to container port 27017 in docker-compose.yml.
• Authentication variant: Two routers (router01 and router02) expose host ports 27117 and 27118 respectively in with-keyfile-auth/docker-compose.yml.
• External access: Mapped ports allow MongoDB clients to connect to localhost:27117 (or 27118) to interact with the sharded cluster without port conflicts.
• Container internals: All routers run mongos on the standard MongoDB port 27017 inside their containers, with Docker handling the network translation.

Frequently Asked Questions

Why are host ports 27117 and 27118 used instead of the standard 27017?

The repository maps non-standard host ports (27117, 27118) to the container's internal 27017 port to avoid conflicts with any MongoDB instance already running on the host machine's 27017 port. This allows developers to run the Docker cluster alongside existing local MongoDB installations without network collisions.

How do I connect to a specific router container from outside Docker?

Connect using the mapped host port rather than the internal container port. For the default configuration, use mongodb://localhost:27117. For the second router in the authentication setup, use mongodb://localhost:27118. Docker automatically forwards traffic from these host ports to port 27017 inside the respective containers.

Can I change the exposed host ports to different values?

Yes, modify the left side of the port mapping in the Docker Compose file. For example, change 27117:27017 to 37017:27017 to expose the router on host port 37017 instead. Ensure the new host port is not already in use by another service on your machine, and update your connection strings accordingly.

What is the difference between the router port mapping in the default and key-file-auth configurations?

The default configuration (docker-compose.yml) defines a single router (router01) mapped to host port 27117. The key-file-auth configuration (with-keyfile-auth/docker-compose.yml) defines two routers for high availability: router01 on host port 27117 and router02 on host port 27118. Both configurations map to container port 27017, but the auth variant provides redundant entry points to the cluster.

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