This guide covers installing MongoDB Community Edition locally, connecting with mongosh, and configuring a development environment that mirrors production patterns.

Prerequisites

  • 64-bit OS (Windows 10+, macOS 12+, Ubuntu 20.04+)
  • At least 4 GB RAM for local development (8 GB+ recommended)
  • Disk space: 10 GB minimum for data and logs

Install on macOS 

  # Install Homebrew if needed: https://brew.sh
brew tap mongodb/brew
brew install [email protected]

# Start as a background service
brew services start [email protected]

# Verify
mongosh --eval "db.runCommand({ connectionStatus: 1 })"

Default data path: /opt/homebrew/var/mongodb (Apple Silicon) or /usr/local/var/mongodb (Intel).

Install on Linux (Ubuntu/Debian) 

  # Import MongoDB GPG key
curl -fsSL https://pgp.mongodb.com/server-7.0.asc | \
  sudo gpg -o /usr/share/keyrings/mongodb-server-7.0.gpg --dearmor

# Add repository (adjust codename for your Ubuntu version)
echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ] \
  https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | \
  sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list

sudo apt-get update
sudo apt-get install -y mongodb-org

sudo systemctl start mongod
sudo systemctl enable mongod
sudo systemctl status mongod

Install on Windows

  1. Download the MSI from the MongoDB Download Center
  2. Run the installer — choose Complete setup
  3. Install MongoDB as a Service (recommended)
  4. Optionally install MongoDB Compass during setup
  5. Add C:\Program Files\MongoDB\Server\7.0\bin to your PATH
  # Verify from PowerShell
mongosh --eval "db.version()"

Install mongosh Separately

mongosh is the modern MongoDB shell (replaces legacy mongo):

  # macOS
brew install mongosh

# Linux — download from MongoDB Download Center
# Windows — included with server MSI or separate download

Configuration File (mongod.conf)

Default locations:

OS Path
Linux /etc/mongod.conf
macOS /opt/homebrew/etc/mongod.conf
Windows C:\Program Files\MongoDB\Server\7.0\bin\mongod.cfg

Development configuration:

  storage:
  dbPath: /var/lib/mongodb
  wiredTiger:
    engineConfig:
      cacheSizeGB: 1

systemLog:
  destination: file
  path: /var/log/mongodb/mongod.log
  logAppend: true

net:
  port: 27017
  bindIp: 127.0.0.1

processManagement:
  timeZoneInfo: /usr/share/zoneinfo

Never bind to 0.0.0.0 without authentication — this exposes your database to the internet.

Start, Stop, and Restart 

  # Linux
sudo systemctl start mongod
sudo systemctl stop mongod
sudo systemctl restart mongod

# macOS
brew services start [email protected]
brew services stop [email protected]

# Windows — use Services app or:
net start MongoDB
net stop MongoDB

First Connection 

  mongosh

# Inside mongosh
show dbs
use dev
db.runCommand({ ping: 1 })   // { ok: 1 }

Create an admin user before enabling auth:

  use admin
db.createUser({
  user: "admin",
  pwd: "StrongPassword123!",
  roles: [{ role: "userAdminAnyDatabase", db: "admin" }]
})

Enable authentication in mongod.conf:

  security:
  authorization: enabled

Restart and reconnect:

  mongosh -u admin -p --authenticationDatabase admin

MongoDB Compass (GUI)

Download from MongoDB Compass.

  • Visual schema exploration and index management
  • Query builder with explain plans
  • Performance monitoring and real-time server stats
  • Connection string: mongodb://localhost:27017

Compass is ideal for exploring data during development; use mongosh for scripting and automation.

Docker Development Setup 

  docker run -d --name mongodb \
  -p 27017:27017 \
  -v mongodb_data:/data/db \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD=secret \
  mongo:7.0

mongosh "mongodb://admin:secret@localhost:27017"

For replica set testing locally, use Docker Compose with three mongod instances — required for transactions and change streams.

Directory Layout 

  /data/db/          — database files (WiredTiger)
/var/log/mongodb/  — server logs
/tmp/mongodb/      — socket files (if configured)

Ensure the mongod user owns data directories on Linux:

  sudo chown -R mongodb:mongodb /var/lib/mongodb /var/log/mongodb

Common Installation Issues

Port 27017 already in use

  sudo lsof -i :27017
# Stop conflicting process or change port in mongod.conf

Permission denied on dbPath

  sudo chown -R mongodb:mongodb /var/lib/mongodb
sudo chmod 755 /var/lib/mongodb

WiredTiger corruption after crash

  # Last resort — repair may lose data; restore from backup first
mongod --repair --dbpath /var/lib/mongodb

macOS “Operation not permitted”

Grant Full Disk Access to Terminal in System Settings → Privacy & Security.

Best Practices

  • Pin a specific version ([email protected]) — avoid surprise upgrades
  • Use separate databases per application in development
  • Enable auth even locally to build correct connection habits
  • Set cacheSizeGB explicitly on dev machines sharing RAM with IDEs
  • Keep logs on a separate partition in production

Production vs Development

Setting Development Production
bindIp 127.0.0.1 Private network IPs only
authorization Recommended Required
Replica set Optional (single node) Minimum 3 members
Backups Optional Automated, tested restores
TLS Optional Required

What Comes Next

With MongoDB running locally, proceed to MongoDB Basics for BSON, collections, CRUD commands, and schema design fundamentals.