Docker provides an excellent way to run MongoDB without installing it directly on your system. This approach offers better isolation, easier version management, and simpler setup. In this guide, I'll walk you through setting up MongoDB with Docker, including common pitfalls and their solutions.

Prerequisites

  • Docker installed on your system
  • Basic knowledge of terminal/command line
  • Root or sudo access to your machine

Step 1: Pull the MongoDB Image

First, pull the latest MongoDB image from Docker Hub:

docker pull mongo:latest

This command downloads the official MongoDB image maintained by MongoDB, Inc.

Step 2: Create Directories for Persistent Storage

Before running MongoDB, you need to create directories for persistent data storage:

mkdir -p ~/mongodb_data
mkdir -p ~/mongodb_backup

Step 3: Set Proper Permissions

This is a critical step that many guides miss! MongoDB inside the container runs as a non-root user (typically with UID 999), and it needs proper permissions to write to the mounted volumes:

# Set ownership to the MongoDB user (typically 999:999 in the container)
sudo chown -R 999:999 ~/mongodb_data
sudo chown -R 999:999 ~/mongodb_backup

# Set restrictive permissions for security
sudo chmod 700 ~/mongodb_data
sudo chmod 700 ~/mongodb_backup

Skipping this step is a common cause of authentication failures and connection issues.

Step 4: Run MongoDB Container

Now, run the MongoDB container with the following parameters:

docker run -d \
  --name mongodb \
  -p 27017:27017 \
  -v ~/mongodb_data:/data/db \
  -v ~/mongodb_backup:/backup \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD=yoursecurepassword \
  --restart always \
  mongo:latest

Let's break down this command:

  • -d: Runs the container in detached mode (background)
  • --name mongodb: Names the container "mongodb" for easy reference
  • -p 27017:27017: Maps the container's port 27017 to the host's port 27017
  • -v ~/mongodb_data:/data/db: Mounts the local directory for persistent data storage
  • -v ~/mongodb_backup:/backup: Mounts a directory for database backups
  • -e MONGO_INITDB_ROOT_USERNAME=admin: Sets the root username
  • -e MONGO_INITDB_ROOT_PASSWORD=yoursecurepassword: Sets the root password
  • --restart always: Ensures the container restarts automatically with the system
  • mongo:latest: Specifies the image to use

Step 5: Verify the Installation

Check if the container is running properly:

docker ps | grep mongodb

You should see your MongoDB container in the list.

Step 6: Connect to MongoDB

Connect to your MongoDB instance using the MongoDB shell:

docker exec -it mongodb mongosh admin --username admin --password yoursecurepassword --authenticationDatabase admin

If you successfully connect, you'll see the MongoDB shell prompt.

Troubleshooting Common Issues

1. Authentication Failed Error

If you see MongoServerError: Authentication failed, check:

  • Whether you're using the correct username and password
  • If the container has fully initialized (check logs with docker logs mongodb)
  • The permissions on your data directory

2. Permission Issues with Mounted Volumes

This is the most common problem when setting up MongoDB with Docker. If MongoDB can't write to the mounted volumes properly, it will fail to initialize or authenticate.

The solution is to correctly set ownership and permissions as shown in Step 3.

3. Container Won't Start or Keeps Restarting

Check the logs:

docker logs mongodb

Look for specific error messages related to permissions, port conflicts, or other initialization issues.

Backing Up Your MongoDB Database

To create a backup:

docker exec -it mongodb mongodump --username admin --password yoursecurepassword --authenticationDatabase admin --out /backup/$(date +%Y%m%d)

This command will create a backup in your ~/mongodb_backup directory with the current date as the folder name.

Restoring a Backup

To restore from a backup:

docker exec -it mongodb mongorestore --username admin --password yoursecurepassword --authenticationDatabase admin /backup/20250323

Replace 20250323 with the actual backup folder name.

Conclusion

Docker provides a clean, isolated environment for running MongoDB without the complexity of a direct installation. By following these steps—especially the often-overlooked permission settings—you can have a robust MongoDB instance running in minutes.

The key lessons:

  1. Always set proper permissions on mounted volumes
  2. Use meaningful container names for easy management
  3. Implement persistent storage for data safety
  4. Configure authentication for security

With this setup, you have a production-ready MongoDB instance that's easy to maintain, backup, and upgrade.