Navigation

Create an Atlas Free Tier Cluster

MongoDB Atlas is a cloud-hosted service for provisioning, running, monitoring, and maintaining MongoDB deployments. It is a fast, easy, and free way to get started with MongoDB. To install and run MongoDB locally, see Install MongoDB.

The following tutorial uses mongo shell to connect to an Atlas free-tier cluster.

MongoDB Compass is the GUI for MongoDB. The following tutorial uses MongoDB Compass to connect to an Atlas free-tier cluster.

The following tutorial uses the PyMongo Python driver to connect to an Atlas free-tier cluster.

The following tutorial uses the MongoDB Node.js Driver to connect to an Atlas free-tier cluster.

1

Create an Atlas user account.

To get started with MongoDB Atlas, create your user account or log in using your existing MongoDB Cloud Manager or JIRA credentials.

2

Create an Atlas Organization.

Choose a name for your organization and click Next.

Screeenshot of the Atlas organization creation form.

Organizations are top-level hierarchy structures. You configure alerts and billing for paid clusters at the organization level, and all projects and clusters part of that organization inherit those settings.

3

Create an Atlas Project.

Choose a name for your project and click Next.

Screeenshot of the Atlas project creation form.

Projects manage related MongoDB deployments, or “clusters” in Atlas. An organization can contain multiple projects. To create additional Atlas Projects, click Projects on the left-hand navigation pane then New Project. For more information, see Projects.

4

Add Members to the Project.

Optional: Add additional Atlas members by entering their email address, pressing enter, and assigning them a role. For more information on roles, see Project Roles. When you are finished adding users, click the Create Project button.

Screeenshot of the adding members to an Atlas project.
5

Create a cluster.

To create a cluster, go to the Clusters view and click the Build a New Cluster button.

  1. In the Cloud Provider & Region panel:

    1. Select Amazon Web Services (AWS).
    2. Choose a region that provides Free Tier; for example: US-EAST-1 or EU-CENTRAL-1.
  2. In the Cluster Tier panel, select M0 for Atlas Free Tier.

    Screenshot of cluster tier panel during creation.
  3. In the Cluster Name panel, enter the name for your cluster.

  4. Click Create Cluster.

6

Setup security.

Screeenshot of cluster security tab on Atlas.

Atlas requires clients to authenticate to access the clusters, i.e. the MongoDB deployment. You must create MongoDB users to access the deployment.

  1. From the Security tab, click MongoDB Users.
  2. Click Add New User.
  3. If you don’t have an Atlas admin user, create an Atlas admin user: enter the username and password and select Atlas admin for the User Privileges. Otherwise, select the desired User Privileges.
  4. Select Add User.
  5. Repeat for additional users.

Atlas only allows client connections to the cluster from entries in the projects’s whitelist. To add an entry to the whitelist:

  1. From the Security tab, click IP Whitelist.
  2. Click Add IP Address. You may either enter the IP address manually in the Whitelist Entry field or click the Add Current IP Address button.
  3. Click Confirm and wait for Atlas to update the firewall.
7

Download the connecting client.

To download the mongo Shell:

  1. Click the Connect button from the Clusters view.
  2. Verify the IP address added in the previous step appears under the Check the IP Whitelist section. You may also add additional IP addresses via the Add Entry button.
  3. Click Connect with the Mongo Shell, select your operating system, and click the Download button.
  4. Extract the download to the desired location or install the mongo shell depending on your operating system.
  5. Optionally, add the <mongodb-install-directory>/bin to your operating system’s PATH or environment variables.

For more operating system specific installation information, see Installation.

To download MongoDB Compass:

  1. Click the Connect button from the Clusters view.
  2. Verify the IP address added in the previous step appears under the Check the IP Whitelist section. You may also add additional IP addresses via the Add Entry button.
  3. Click Connect with MongoDB Compass, select your operating system, and click the Download button.
  4. Run the installer.

Install the PyMongo driver via pip:

python -m pip install pymongo

For more information, see Installing PyMongo.

First create your project using npm init then install the MongoDB Node.js Driver via npm:

npm install mongodb --save

For more information, see the Node.js driver Quick Start documentation.

8

Get the URI connection string.

From the Connect with the Mongo Shell modal:

  1. Beneath the Download button from the previous step, specify which version of the Mongo Shell you are using for the 2. Connect via the Mongo Shell section.

  2. Select the version of the shell and copy the URI Connection String to the clipboard.

  3. Paste the connection string somewhere and replace <PASSWORD> with the password for the user created earlier. The sample connection string connects to the test database which is used by the following examples. If you wish to connect to a different database, change test to whichever database you wish to connect to.

    Note

    Atlas automatically chooses a username from the list of the project’s configured MongoDB users. Replace the username with another MongoDB user in that project if necessary.

  4. Copy the modified connection string to the clipboard.

From the Connect to Compass modal:

  1. Copy the URI Connection String to the clipboard located below the Download button from the previous step.

  2. Paste the connection string somewhere and replace <PASSWORD> with the password for the user created earlier.

    Note

    Atlas automatically chooses a username from the list of the project’s configured MongoDB users. Replace the username with another MongoDB user in that project if necessary.

  3. Copy the modified connection string to the clipboard.

  1. Click the Connect button from the Clusters view.

  2. Verify the IP address added earlier appears under the Check the IP Whitelist section. You may also add additional IP addresses via the Add Entry button.

  3. Click Connect Your Application.

  4. Specify which driver version you are using for the Copy a connection string section.

  5. Copy the URI Connection String to the clipboard.

  6. Paste the clipboard contents into your preferred text editor and replace <PASSWORD> with the password for the user created earlier. The sample connects to the test database which the following examples use. If you wish to connect to a different database, change test to whichever database you wish to connect to.

    Note

    Atlas automatically chooses a username from the list of the project’s configured MongoDB users. Replace the username with another MongoDB user in that project if necessary.

  7. Copy the modified connection string to the clipboard.

  1. Click the Connect button from the Clusters view.

  2. Verify the IP address added earlier appears under the Check the IP Whitelist section. You may also add additional IP addresses via the Add Entry button.

  3. Click Connect Your Application.

  4. Specify which driver version you are using for the Copy a connection string section.

  5. Copy the URI Connection String to the clipboard.

  6. Paste the clipboard contents into your preferred text editor and replace <PASSWORD> with the password for the user created earlier. The sample connects to the test database which the following examples use. If you wish to connect to a different database, change test to whichever database you wish to connect to.

    Note

    Atlas automatically chooses a username from the list of the project’s configured MongoDB users. Replace the username with another MongoDB user in that project if necessary.

  7. Copy the modified connection string to the clipboard.

9

Connect to the cluster.

Using the connection string from the previous step, connect to the Atlas cluster:

<mongodb-install-directory>/bin/mongo "mongodb+srv://mycluster-ma4u7.mongodb.net/test" --username mongodbusername

Alternatively, if you added <mongodb-install-directory>/bin to the PATH then you may run:

mongo "mongodb+srv://mycluster-ma4u7.mongodb.net/test" --username mongodbusername

For Windows, run:

"C:\Program Files\MongoDB\Server\4.0\bin\mongo.exe" "mongodb+srv://mycluster-ma4u7.mongodb.net/test" --username mongodbusername
  1. Launch MongoDB Compass with the connection string from the previous step copied to the clipboard.

  2. A dialog box will prompt you to use the URI to fill out the connect form. Click Yes.

    Screeenshot of URI prompt on Compass connect screen.
  3. Enter the Password.

  4. Optionally enter a Favorite Name and click Create Favorite to save these settings under Favorites to connect more quickly in future sessions.

    Screeenshot of a completed Compass connect form.
  5. Click Connect.

from pymongo import MongoClient

client = pymongo.MongoClient("mongodb://user123:p455w0rd@gettingstarted-shard-00-00-hyjsm.mongodb.net:27017,gettingstarted-shard-00-01-hyjsm.mongodb.net:27017,gettingstarted-shard-00-02-hyjsm.mongodb.net:27017/test?ssl=true&replicaSet=GettingStarted-shard-0&authSource=admin")
db = client.test

# Paste the following examples here
var MongoClient = require('mongodb').MongoClient;

var uri = "mongodb://user123:p455w0rd@gettingstarted-shard-00-00-hyjsm.mongodb.net:27017,gettingstarted-shard-00-01-hyjsm.mongodb.net:27017,gettingstarted-shard-00-02-hyjsm.mongodb.net:27017/test?ssl=true&replicaSet=GettingStarted-shard-0&authSource=admin";
MongoClient.connect(uri, function(err, db) {
  // Paste the following examples here

  db.close();
});

Next Steps

Follow the Getting Started tutorial to insert data into MongoDB and perform query operations.