Practical Guide: Running MongoDB in Docker Containers

On multi-environment platforms—whether local or CI—the need for isolated, disposable databases is constant. Installing MongoDB locally remains an option, but containers are the obvious path when you need repeatability and speed.

Motivation

Containerizing MongoDB offers several engineering benefits:

• Clean reproducibility. Spin up identical environments for every project.
• Resource isolation. No cross-talk between database processes.
• Version pinning. Specify MongoDB tags to avoid unexpected upgrades.

Baseline Requirements

• Docker Engine 20.10+ (docs)
• (Recommended) Docker Compose v2+ for multi-service orchestration
• Terminal with proper permissions (docker group on Linux)

Note: SELinux or AppArmor might interfere with volume mounts; troubleshoot accordingly on hardened systems.

Pull and Run a Standalone MongoDB Container

Start with the official Docker image for MongoDB 6.0 (latest LTS as of mid-2024):

docker pull mongo:6.0

Basic ephemeral usage:

docker run -d --name mongodb-test -p 27017:27017 mongo:6.0

Key flags:

Verify status:

docker ps --filter name=mongodb-test

You should see a line similar to:

CONTAINER ID   IMAGE       COMMAND                  STATUS          PORTS                      NAMES
7f1e1d230f45   mongo:6.0   "docker-entrypoint.s…"   Up 15 seconds   0.0.0.0:27017->27017/tcp   mongodb-test

Data Persistence (Non-Ephemeral Containers)

Containers die; data shouldn’t. MongoDB writes to /data/db inside the container. Mount a volume:

docker run -d --name mongodb-persist \
  -p 27017:27017 \
  -v mongodbdata:/data/db \
  mongo:6.0

Docker manages the mongodbdata volume lifecycle. To see it:

docker volume inspect mongodbdata

Trade-off: Host directories can be used instead of named volumes for explicit file access or backup, but permissions and SELinux issues are more likely.

Local Shell Access: Host and Container

If your host has the MongoDB CLI:

mongo --host localhost --port 27017

Or run it inside the container (requires Mongo tools image in MongoDB 6.2+):

docker exec -it mongodb-persist mongosh

Side note: In v6.2+, the legacy mongo shell is removed. Use mongosh for newer images.

Typical insert and query cycle:

use localtest
db.servers.insertOne({name: "dev01", ip: "10.0.0.123"})
db.servers.find({name: "dev01"})

Orchestrating with Docker Compose

For nontrivial environments, prefer docker-compose. Example configuration (filename: docker-compose.yml):

version: "3.8"

services:
  mongodb:
    image: mongo:6.0
    restart: unless-stopped
    ports:
      - "27017:27017"
    volumes:
      - mongodbdata:/data/db

volumes:
  mongodbdata:

Start with:

docker-compose up -d

Services now have network aliases by default. In Compose, other services reach MongoDB at mongodb:27017.

Common Operational Issues

• Port collision:

  Error response from daemon: driver failed programming external connectivity on endpoint...
  

  Another process (possibly an old MongoDB server) binds to 27017. Use a non-standard host port:
  -p 27018:27017
  Adjust client connections accordingly.

• Container won’t start, logs show:

  Data directory /data/db not writable by user mongodb
  

  Most often a permissions mismatch on mounted host directories. Named volumes avoid this.

• Data resets after restart
  Ephemeral containers don’t persist. Confirm volume usage via docker inspect.

Practical Scenario: Test Environment Reset

Quick “Nuke and Reset” Loop

To kill and re-provision:

docker stop mongodb-persist && docker rm mongodb-persist
docker volume rm mongodbdata  # Be careful—this deletes all data!
docker run -d --name mongodb-persist -p 27017:27017 -v mongodbdata:/data/db mongo:6.0

This cycle is valuable when testing destructive schema migrations.

Advanced Config: Authentication

For anything beyond quick local tests, always supply credentials:

docker run -d --name mongodb-auth \
  -p 27017:27017 \
  -v mongodbdata:/data/db \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD=changeme \
  mongo:6.0

Define users, and your application connects with credentials.
Don't use these values in production.

Conclusion

Containerized MongoDB aligns with modern ephemeral, disposable development workflows. Critical details—like explicit version tagging and data volume configuration—can prevent hours of debugging later. For production, harden with proper user ACLs, backups, and healthchecks.

Alternative: Podman offers a Docker-compatible CLI and works similarly (including named volumes), but integration with Compose still has edge-case quirks.

Gotcha: MongoDB isn’t “stateless” by default—always plan storage, even for local dev, unless you intentionally want throwaway data.