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.

MongoDB clusters can be either a replica set or a sharded cluster.

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

  1. Enter a Cluster Name.
  2. Select Amazon Web Services as the Cloud Provider.
  3. For Region, chose either US-EAST-1 or EU-CENTRAL-1.
  4. Click the Select button for Instance Size M0 for Atlas Free Tier.
Screenshot of cluster config options during creation.
  1. Enter a Username and Password.

    Screenshot of admin username and password fields that appear only when admin user doesn't exist.

    These fields appear only if no MongoDB user exists for your Atlas project. If you created users in the project beforehand these fields will not appear.

  2. Click Confirm & Deploy.

6

Setup security.

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

Screeenshot of cluster security tab on Atlas.
  1. Click the Security tab from the Clusters view.
  2. Click IP Whitelist, then 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. 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://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"

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

mongo "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"

For Windows, run:

"C:\Program Files\MongoDB\Server\3.6\bin\mongo.exe" "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"
  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.