The place for .NET enthusiasts, Azure lovers, and backend developers

First steps with Docker: download and run MongoDB locally

2020-05-12 5 min read Blog

Docker is a project that allows you to create and run applications in an isolated environment. Let’s try it to run MongoDB on your machine!

Table of Contents

Just a second!
If you are here, it means that you are a software developer. So, you know that storage, networking, and domain management have a cost .

If you want to support this blog, please ensure that you have disabled the adblocker for this site. I configured Google AdSense to show as few ADS as possible - I don't want to bother you with lots of ads, but I still need to add some to pay for the resources for my site.

Thank you for your understanding.
- Davide

In this article, I’m going to explain how you can try out the functionalities of MongoDB without installing it, but running it on a Docker container. First of all, I’ll explain what is Docker and what it can do for us; then we’ll run MongoDB on a Docker container.


You’ve probably heard of Docker: it is an open-source project that allows developers to run, create and distribute unit of software in a standardized way; it works with containers, that, simplifying a lot, are isolated applications with their own file systems and that can be run anywhere: think of them as VMs, but with a different and lighter underlying structure.

First of all, you must install Docker on your machine. You can refer to the Getting Started page on the project’s website to know how to download and install it.

But, first, let me introduce the key concepts to know about Docker: images and containers.

Docker images

Images are the blueprints that contain all the information to run a container. Do you remember snapshots from the VM world? Well, images are the same for containers: a set of instructions and file system layers that, when executed, allow your container to be alive.

Most of the images are available on DockerHub: this is a library of official images of various types, from databases to frameworks, from operating systems to cache platforms.

There are few commands to know when working with images:

  • docker pull <image-name> downloads the specified image from Docker Hub;
  • docker image ls lists all the downloaded images stored on your machine;
  • docker rmi <image-name> removes the specified image from your machine;

Docker containers

Containers are the living versions of an image.

Once you have downloaded an image, you can “build” it to have your container up and running:

  • docker run <image-name> creates and runs a container using the specified image;
  • docker ps lists all the containers currently up;
  • docker ps -a lists all the containers, also the ones stopped;
  • docker stop <container-name> stops the specified container;
  • docker rm <container-name> stops and removes the specified container;

So now we have our container accessible within the machine. But we haven’t finished yet!

Docker containers ports

Once the container is up and running, it exposes one or more ports (for example, the container for an API may expose port 80). But that ports belong to the container! Since we need to access the container from our localhost, we need to map a local port to one of the ports exposed by the container.

If the container exposes the port 80, we can run docker run -p 8089:80 image-name. The -p flag maps the external and the internal ports, allowing us to access the container navigating to localhost:8089.

How port mapping works


MongoDB is a document-based database. Just like you have tables and relations in a relational database, for document databases the focus is on documents: those are dynamic structures, meaning that they don’t have a strict schema, but can be extended as you wish. MongoDB stores documents in a JSON format; for example, this is a valid document:

  "_id": "5cf0029caff5056591b0ce7d",
  "firstname": "Davide",
  "lastname": "Bellone",
  "address": {
    "city": "Turin",
    "country": "Italy"
  "hobbies": ["coding", "music", "blogging"]

Documents are stored inside collections that represent, well, collections of documents! Obvious, isn’t it? 😊 Usually, collections are meant to group similar documents, such as users, books, and so on.

Do you want to try it? Maybe without installing it? Here’s where Docker comes in handy.

Running MongoDB on Docker

The first step is to download the official MongoDB image using the terminal:

docker pull mongo

docker pull mongo result

We can check the details of this image by running docker image inspect mongo: this command will list all the properties of this image; we can see, looking at the ContainerConfig.ExposedPorts field, that we can reach Mongo through port 27017.

exposed port

So now we are ready to run this container with this command:

docker run -d  --name mongo-on-docker  -p 27888:27017 -e MONGO_INITDB_ROOT_USERNAME=mongoadmin -e MONGO_INITDB_ROOT_PASSWORD=secret mongo

It looks complicated, right? Let me explain every part:

  • docker run runs the image and starts the container;
  • -d runs the container in background, so that we are free to use the current terminal instance;
  • --name mongo-on-docker defines a friendly name for the container;
  • -p 27888:27017 declares that the local port 27888 is mapped to the internal 27017 port;
  • -e MONGO_INITDB_ROOT_USERNAME=mongoadmin sets the root username (-e sets the environment variables);
  • -r MONGO_INITDB_ROOT_PASSWORD=secret sets the root password;
  • mongo is the name of the image to run;

That’s it! Now you have your MongoDB instance up and running without having it installed directly on your machine!

It’s time to try it: create your connection string with this format: mongodb://<username>:<password>@<host>:<port>/?authSource=admin. You will get mongodb://mongoadmin:secret@localhost:27888/?authSource=admin.

Now, if you have a tool for exploring MongoDB, open it and connect to the newly created Mongo instance. If you use NoSQLBooster for MongoDB you will see something like this:

MongoDB instance

Finally, you can create a new DB (I’ve called it tests) and try MongoDB.

This article first appeared on Code4IT

Wrapping up

Thanks to Docker now it’s possible to run many platforms on your local machine without installing them. You can use Docker for many other purposes, like creating your own images and container, organize and connect them, and many other cool stuff.

Happy coding!