Codakey
Play
← Back to mongodb/mongo

How to Deploy & Use mongodb/mongo

# MongoDB Deployment & Usage Guide

## 1. Prerequisites

### System Requirements
- **OS**: Linux (RHEL 8+, Ubuntu 20.04+), macOS 10.14+, Windows 10/Server 2016+
- **Architecture**: x86_64, ARM64, or s390x
- **Memory**: Minimum 4GB RAM (8GB+ recommended for building from source)
- **Disk**: 10GB+ free space for binaries; additional space for data storage
- **Compiler** (for building from source): GCC 11+ or Clang 14+

### Required Tools
- **Git** 2.20+
- **Python** 3.7+ (required for build scripts)
- **SCons** 4.0+ (MongoDB's build system)
- **OpenSSL** 1.1.1+ or 3.0+
- **C++ toolchain**: `build-essential` (Ubuntu/Debian), `Development Tools` (RHEL/CentOS), or Xcode Command Line Tools (macOS)

### Optional Tools
- **mongosh**: MongoDB Shell for database interaction
- **Docker**: For containerized deployment
- **Homebrew** (macOS): For simplified installation

## 2. Installation

### Option A: Pre-built Binaries (Recommended for Production)

**Linux/macOS via Package Manager:**
```bash
# macOS Homebrew
brew tap mongodb/brew
brew install mongodb-community

# Ubuntu/Debian (see official docs for latest repository setup)
wget -qO - https://www.mongodb.org/static/pgp/server-7.0.asc | sudo apt-key add -
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/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

# RHEL/CentOS
sudo yum install -y mongodb-org

Docker:

docker pull mongodb/mongodb-community-server:latest

Direct Download: Visit https://www.mongodb.com/try/download/community and select your platform.

Option B: Build from Source (Development)

# Clone repository
git clone https://github.com/mongodb/mongo.git
cd mongo

# Install Python dependencies
python3 -m pip install -r etc/pip/compile-requirements.txt

# Build MongoDB (this may take 1-4 hours depending on hardware)
python3 buildscripts/scons.py install-mongod install-mongos --disable-warnings-as-errors

# Binaries will be in the install/ directory

3. Configuration

Data Directory Setup

# Create default data directory (requires root for /data path)
sudo mkdir -p /data/db
sudo chown -R $(whoami) /data/db

# Or use custom path
mkdir -p ~/mongodb/data

Configuration File (mongod.conf)

Create /etc/mongod.conf or ~/mongodb/mongod.conf:

storage:
  dbPath: /data/db
  journal:
    enabled: true

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

net:
  port: 27017
  bindIp: 127.0.0.1

processManagement:
  fork: true
  pidFilePath: /var/run/mongodb/mongod.pid

security:
  authorization: disabled  # Enable for production: enabled

Environment Variables

# Add to ~/.bashrc or ~/.zshrc
export PATH=$PATH:/usr/local/mongodb/bin
export MONGO_DATA=/data/db

4. Build & Run

Development Mode

Build specific targets:

# Build only the database server
python3 buildscripts/scons.py mongod

# Build the sharding router
python3 buildscripts/scons.py mongos

# Build with debug symbols
python3 buildscripts/scons.py --dbg=on mongod

Run single node instance:

# From source build
./mongod --dbpath /data/db --logpath /var/log/mongodb/mongod.log --fork

# Or with config file
./mongod --config /etc/mongod.conf

Connect with shell:

# Install mongosh separately if not included
brew install mongosh  # macOS
# or download from https://www.mongodb.com/try/download/shell

mongosh
# Default connects to mongodb://localhost:27017/test

Production Mode

Start with authentication:

# Initialize replica set (required for auth)
mongod --replSet rs0 --dbpath /data/db

# In another terminal, initiate replica set
mongosh --eval "rs.initiate()"

# Create admin user
mongosh admin --eval "db.createUser({user: 'admin', pwd: 'password', roles: ['root']})"

# Restart with auth enabled
mongod --config /etc/mongod.conf --auth

Install Compass (GUI):

./install_compass  # Run script from MongoDB distribution

5. Deployment

Docker Deployment

# Single instance
docker run -d \
  --name mongodb \
  -p 27017:27017 \
  -v /my/local/data:/data/db \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD=secret \
  mongodb/mongodb-community-server:latest

# With replica set
docker run -d \
  --name mongo-replica \
  -p 27017:27017 \
  -v mongo-data:/data/db \
  mongodb/mongodb-community-server:latest \
  --replSet rs0

Systemd Service (Linux)

Create /etc/systemd/system/mongod.service:

[Unit]
Description=MongoDB Database Server
After=network.target

[Service]
Type=forking
User=mongodb
Group=mongodb
ExecStart=/usr/bin/mongod --config /etc/mongod.conf
ExecStop=/usr/bin/mongod --shutdown --config /etc/mongod.conf
PIDFile=/var/run/mongodb/mongod.pid
Restart=always

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable mongod
sudo systemctl start mongod

Sharded Cluster (Production)

# Config servers (run on 3 separate nodes)
mongod --configsvr --replSet configRS --port 27019 --dbpath /data/configdb

# Shard servers (run on multiple nodes)
mongod --shardsvr --replSet shard1RS --port 27018 --dbpath /data/shard1

# Mongos router
mongos --configdb configRS/config1:27019,config2:27019,config3:27019 --port 27017

Cloud Deployment

  • MongoDB Atlas: https://www.mongodb.com/cloud/atlas (Managed service)
  • AWS/Azure/GCP: Use marketplace images or install via package managers
  • Kubernetes: Use MongoDB Community Kubernetes Operator

6. Troubleshooting

Build Issues

Error: "No module named 'scons'"

pip3 install scons
# Or use the bundled version
python3 buildscripts/scons.py [options]

Error: "Insufficient disk space"

  • Ensure 50GB+ free space for full build with debug symbols
  • Use --link-model=dynamic to reduce binary sizes

Compilation failures on ARM64

  • Ensure you have the latest Xcode (macOS) or GCC 11+ (Linux)
  • Add --disable-warnings-as-errors to bypass strict warnings

Runtime Issues

Error: "Unable to create/open lock file"

# Fix permissions
sudo chown -R $(whoami) /data/db
# Or run with custom dbpath
mongod --dbpath ~/mongodb/data

Error: "Address already in use"

# Kill existing process
sudo pkill mongod
# Or use different port
mongod --port 27018

SELinux/AppArmor blocking access (Linux)

# For SELinux
sudo chcon -R -t mongod_var_lib_t /data/db
sudo setsebool -P mongod_can_connect 1

# For AppArmor
sudo aa-complain /etc/apparmor.d/usr.bin.mongod

High memory usage during build

  • Limit parallel jobs: -j2 or -j4 instead of default (all cores)
  • Add --allocator=system to use system malloc during build

Connection Issues

"Connection refused" from remote host

  • Check bindIp in config (change from 127.0.0.1 to 0.0.0.0 for external access)
  • Verify firewall rules: sudo ufw allow 27017/tcp
  • Check if replica set is initiated when using --replSet

Authentication failures

  • Ensure you're connecting to admin database for initial auth: 
    mongosh -u admin -p --authenticationDatabase admin

Log Analysis

# View logs
tail -f /var/log/mongodb/mongod.log

# Check for slow queries
mongosh --eval "db.system.profile.find().sort({ts:-1}).limit(5)"

For additional support, visit:

← Project overviewView alternatives to mongodb/mongo →