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

> Expose MongoDB router ports externally using Docker Compose with HOST:CONTAINER syntax. Learn how to map port 27017 to distinct host ports for seamless client connections.

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

---

**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/main/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:

```yaml
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/main/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):**

```yaml
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):**

```yaml
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:

```bash
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:

```bash
mongo --host localhost --port 27117

```

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

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

```

Using a connection string in application code:

```python
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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/docker-compose.yml).
- **Authentication variant**: Two routers (`router01` and `router02`) expose host ports **27117** and **27118** respectively in [`with-keyfile-auth/docker-compose.yml`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/docker-compose.yml)) defines a single router (`router01`) mapped to host port 27117. The **key-file-auth configuration** ([`with-keyfile-auth/docker-compose.yml`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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.