Spring Boot Mastery: Installing MongoDB on Mac, Lubuntu, Fedora, and Windows 11

This chapter provides a comprehensive, step-by-step guide to installing and configuring MongoDB across the four major operating systems: Windows 11, Ubuntu/Lubuntu, Fedora, and macOS. You will learn how to set up the MongoDB Community Server, manage the background database service, interact with the database using the MongoDB Shell (mongosh), and utilize MongoDB Compass as a graphical user interface (GUI).

1. Why Do We Need This? (The Database Ecosystem)

When developing modern applications with Spring Boot, choosing a flexible, schema-less database is often essential for handling unstructured or semi-structured data. MongoDB is a leading document-oriented NoSQL database that stores data in flexible, JSON-like documents (BSON).

To work with MongoDB effectively on your local development machine, you need to understand the three core pillars of the MongoDB ecosystem:

• MongoDB Server (mongod): The core database engine that runs in the background, listens for connections on a network port, and manages data storage and retrieval.
• MongoDB Shell (mongosh): A command-line interface (CLI) that allows developers to connect to the server, run administrative commands, and execute database queries directly.
• MongoDB Compass: A graphical user interface (GUI) that provides a visual representation of your databases, collections, and documents, making it easier to analyze schemas and build queries without writing raw code.

2. Core Mental Model & Architecture

MongoDB operates on a classic client-server architecture. The database server runs as a background service, listening on a designated port (default: 27017). Any client application—whether it is your Spring Boot application, the MongoDB Shell, or MongoDB Compass—must connect to this port to perform operations.

Client-Server Communication Flow

Real-Life Analogy

Think of the MongoDB Server as a secure physical warehouse. The warehouse manager (mongod) is always inside, waiting for requests.

• MongoDB Compass is like a high-tech control room with video screens showing everything inside the warehouse.
• MongoDB Shell is like a walkie-talkie system where you must speak specific, structured commands to the manager to get things done.
• The Port (27017) is the specific gate number through which all communication and transport must pass.

3. Windows 11 Installation Guide

Installing MongoDB on Windows 11 involves setting up the Community Server as a Windows Service, installing MongoDB Compass, and configuring the MongoDB Shell (mongosh) separately.

Step 1: Download the Installer

1. Navigate to the official MongoDB website and search for the MongoDB Community Server Download.
2. Select the following options:
   • Version: Current stable version (e.g., 7.x.x or 8.x.x)
   • Platform: Windows
   • Package: MSI (Microsoft Installer)
3. Click Download (the file size is approximately 400 MB).

Step 2: Run the MSI Installer

1. Double-click the downloaded .msi file to launch the setup wizard.
2. Click Next, accept the End-User License Agreement, and click Next.
3. Choose the Complete setup type.
4. On the Service Configuration screen, ensure "Install MongoDB as a Service" is checked.
   • This configures MongoDB to run automatically in the background when Windows starts.
   • Keep the default Service Name (MongoDB), Data Directory, and Log Directory paths.
5. Click Next.
6. On the next screen, ensure "Install MongoDB Compass" is checked to automatically install the GUI tool.
7. Click Install and then click Finish. MongoDB Compass will launch automatically upon completion.

Step 3: Managing the Windows Service

You can control the background database engine using either the graphical Services console or the Command Prompt (CMD).

Method A: Graphical Services Console

1. Press Win + R, type services.msc, and press Enter.
2. Scroll down to find MongoDB Server.
3. Right-click the service to Start, Stop, or Restart it.

Method B: Command Line (CMD)

To manage the service via the command line, you must run the Command Prompt as an Administrator.

# Stop the MongoDB background service
net stop MongoDB

# Start the MongoDB background service
net start MongoDB

Note: If you run these commands in a standard, non-elevated command prompt, you will receive an Access Denied error.

Step 4: Installing and Configuring MongoDB Shell (mongosh)

Starting with newer versions, the MongoDB Shell is distributed as a separate package.

1. Search for MongoDB Shell Download on Google.
2. Select the Windows 64-bit platform and download the MSI package.
3. Run the installer. When prompted for the installation path, you can customize it (e.g., C:\mongoSH\).
4. Once installed, navigate to the installation directory or add the directory to your system's PATH environment variable.
5. Open a terminal and run the shell:
   BASH

   Copy

   mongosh
   

6. By default, it connects to mongodb://localhost:27017.
7. Test the connection by listing the default databases:
   JAVASCRIPT

   Copy

   show dbs
   

8. To exit the shell, press Ctrl + C or type exit.

4. Ubuntu / Lubuntu Installation Guide

For Debian-based Linux distributions like Ubuntu and Lubuntu, MongoDB is installed using the official MongoDB repository and the apt package manager.

Step-by-Step Terminal Execution

Open your terminal and execute the following commands sequentially:

1. Install Prerequisites

Ensure your system has gnupg and curl installed:

sudo apt-get install gnupg curl

2. Import the Public GPG Key

Import the official MongoDB public GPG key to verify package integrity:

curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | \
   sudo gpg --o /usr/share/keyrings/mongodb-server-7.0.gpg \
   --dearmor --yes

3. Add the MongoDB Repository

Create the list file for your specific Ubuntu version (e.g., Ubuntu 22.04 Jammy):

echo "deb [ arch=amd64,arm64 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

4. Reload the Local Package Database

Update your local package index:

sudo apt-get update

5. Install MongoDB Packages

Install the complete MongoDB package suite:

sudo apt-get install -y mongodb-org

(This installation will use approximately 524 MB of disk space.)

6. Manage the MongoDB Service

Use systemctl to start and manage the background daemon (mongod):

# Start the service
sudo systemctl start mongod

# Verify the service status (should show "active (running)")
sudo systemctl status mongod

# Enable MongoDB to start automatically on system boot
sudo systemctl enable mongod

# Stop the service
sudo systemctl stop mongod

# Restart the service
sudo systemctl restart mongod

7. Verify via Process List

You can also verify that the process is running using ps:

ps -ef | grep mongod

8. Connect to the Shell

Launch the interactive shell:

mongosh

Inside the shell, verify the installation by running:

show dbs

5. Fedora Installation Guide

On Red Hat-based distributions like Fedora, packages are managed using the dnf package manager. Because MongoDB is not included in the default Fedora repositories, you must manually add the official MongoDB repository configuration.

Step 1: Add the MongoDB Repository Configuration

Create and edit a new repository file using sudo:

sudo vi /etc/yum.repos.d/mongodb-org.repo

Paste the following configuration details into the file (this example configures the stable 4.4 or 7.0 repository depending on your target version):

[mongodb-org]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/$releasever/mongodb-org/7.0/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://www.mongodb.org/static/pgp/server-7.0.asc

Save and close the file (in vi, press Esc, type :wq, and press Enter).

Step 2: Install MongoDB Packages

Run the installation command via dnf:

sudo dnf install -y mongodb-org mongodb-org-server

Step 3: Manage the Service

Enable and start the service so it runs persistently:

# Enable the service to start on boot
sudo systemctl enable mongod

# Start the service immediately
sudo systemctl start mongod

# Check the active status
sudo systemctl status mongod

Step 4: Verify Installation and Version

Verify that the binary is installed and check its version:

mongod --version

Step 5: Interact via Shell

Launch the shell (depending on the installed version, use mongo or mongosh):

mongosh

Inside the shell, you can run database commands:

// List all databases
show dbs

// Switch to a specific database (creates it if it doesn't exist)
use college

// Show collections in the current database
show collections

// Query documents inside a collection
db.teachers.find()

6. macOS Installation Guide (Intel & Apple Silicon)

On macOS, the recommended installation method is using Homebrew, the popular package manager for macOS.

Step 1: Install Xcode Command Line Tools

MongoDB requires compilation and system utilities provided by the Xcode Command Line Tools. Open your terminal and run:

xcode-select --install

If they are already installed, the system will output an error stating that they are already present; you can safely proceed to the next step.

Step 2: Install Homebrew (If Not Present)

If you do not have Homebrew installed, run the official installation script:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Step 3: Tap the MongoDB Homebrew Repository

Add the official MongoDB Homebrew tap to your system:

brew tap mongodb/brew

Step 4: Update Homebrew

Ensure your local Homebrew formulae are up to date:

brew update

Step 5: Install MongoDB Community Server

Install the latest stable community edition (e.g., version 7.0):

brew install mongodb-community@7.0

Troubleshooting Outdated Command Line Tools: If the installation fails with an error stating Your command line tools are too outdated, open your macOS System Settings -> General -> Software Update and install any pending command line tool or system updates. Once updated, re-run the brew install command.

Step 6: Start the MongoDB Service

To run MongoDB as a background service managed by Homebrew Services:

brew services start mongodb-community@7.0

Alternative: Running Manually in the Foreground (Apple Silicon M1/M2/M3)

If you prefer to run the MongoDB process manually in the foreground without letting Homebrew manage it as a background daemon:

mongod --config /opt/homebrew/etc/mongod.conf

Step 7: Verify the Process

Check if the mongod process is running successfully:

ps aux | grep mongod

Step 8: Connect to the Shell

Launch the MongoDB Shell to verify the connection:

mongosh

Inside the shell, run:

show dbs

7. Comparative Synthesis of Commands & Paths

The following table synthesizes the installation, service management, and configuration details across all four operating systems:

8. Troubleshooting & Common Pitfalls

1. Windows "Access Denied" Error

• Symptom: Running net stop MongoDB or net start MongoDB results in an Access Denied error.
• Reason: The command prompt does not have administrative privileges.
• Solution: Search for cmd in the Windows Start Menu, right-click on Command Prompt, and select Run as Administrator.

2. macOS Outdated Command Line Tools

• Symptom: brew install fails with a compilation or toolchain error.
• Reason: The installed Xcode Command Line Tools do not match the current macOS system version.
• Solution: Run xcode-select --install or update the tools via System Settings -> Software Update.

3. Port 27017 Already in Use

• Symptom: The MongoDB service fails to start, or logs show Address already in use.
• Reason: Another instance of MongoDB or another application is already bound to port 27017.
• Solution: Find and terminate the process occupying the port:
  • Linux/macOS: sudo lsof -i :27017 followed by kill -9 <PID>
  • Windows: netstat -ano | findstr 27017 followed by taskkill /F /PID <PID>

4. Database Connection Refused

• Symptom: Running mongosh returns a connection error.
• Reason: The background database engine (mongod) is not running.
• Solution: Verify the service status using the appropriate command for your OS (e.g., sudo systemctl status mongod or checking the Windows Services panel) and start the service.

9. Summary and Key Takeaways

• Core Components: Setting up MongoDB requires installing the Server (mongod background engine), the Shell (mongosh command-line interface), and optionally Compass (the graphical user interface).
• Default Port: MongoDB always listens on port 27017 by default.
• Windows Service: During the Windows installation, configuring MongoDB as a service ensures it starts automatically on boot, eliminating the need to manually launch the server executable every time.
• Windows CLI Management: Admin privileges are strictly required to start or stop the MongoDB service via Windows Command Prompt using net start MongoDB and net stop MongoDB.
• Linux Service Management: On both Ubuntu and Fedora, the system daemon manager systemctl is used to control, enable, and monitor the mongod service.
• Fedora Repositories: Fedora requires you to manually create a .repo file under /etc/yum.repos.d/ before installing MongoDB via dnf.
• macOS Homebrew: Homebrew is the standard tool for installing MongoDB on macOS. It manages the background daemon seamlessly via brew services.
• Verification: Regardless of the operating system, running the mongosh command and executing show dbs is the standard way to verify a successful, active installation.