How to Deploy MongoDB on Heroku
Rate this tutorial
As we begin building more cloud-native applications, choosing the right services and tools can be quite overwhelming. Luckily, when it comes to choosing a cloud database service, MongoDB Atlas may be the easiest choice yet!
When paired with Heroku, one of the most popular PaaS solutions for developers, you'll be able to build and deploy fully managed cloud applications in no time. The best part? MongoDB Atlas integrates easily with Heroku applications. All you need to do is set your Atlas cluster's connection string to a Heroku config variable. That's really all there is to it!
If you're already familiar with MongoDB, using MongoDB Atlas with your cloud applications is a natural choice. MongoDB Atlas is a fully-managed cloud database service for MongoDB that automates the management of MongoDB clusters in the cloud. Offering features such as automated backup, auto-scaling, multi-AZ fault tolerance, and a full suite of management and analytics tools, Atlas is the most sophisticated DBaaS anywhere, and is just a few clicks away.
To see how quick it is to get up and running with MongoDB Atlas, just follow the next few steps to set up your first free cluster. Then, see how quickly you can connect your new Atlas cluster to your Heroku application by following the step-by-step instructions later on in this tutorial.
This tutorial assumes the following:
- You are familiar with MongoDB and have written applications that use MongoDB.
- You are familiar with Heroku and know how to deploy Heroku apps. - You have the Heroku CLI installed.
With these assumptions in mind, let's get started!
💡 If you already created a MongoDB account using your email address, you can skip this step! Sign into your account instead.
After registering, Atlas will prompt you to create an organization and project where you can deploy your cluster.
You'll now be able to select from a range of cluster options. For this tutorial, we'll select the Shared Clusters option, which is Atlas's Free Tier cluster. Click "Create a cluster" under the Shared Clusters option:
On the next page, you'll be prompted to choose a few options for your cluster:
Cloud provider & region
Choose where you want to deploy your cluster to. It is important to select the available region closest to your application, and ideally the same region, in order to minimize latency. In our case, let's choose the N. Virginia (us-east-1) region, with AWS as our cloud provider (since we're deploying on Heroku, and that is where Heroku hosts its infrastructure):
Cluster tier
Here, you'll see the cluster tiers available for the shared clusters option. You can view a comparison of RAM, Storage, vCPU, and Base Price between the tiers to help you choose the right tier. For our tutorial, leave the default M0 Sandbox tier selected:
Additional settings
Depending on the tier you choose, some additional options may be available for you. This includes the MongoDB version you wish to deploy and, for M2 clusters and up, Backup options. For this tutorial, select the latest version, MongoDB 4.4:
Cluster name
Lastly, you can give your cluster a name. Keep in mind that once your cluster is created, you won't be able to change it! Here, we'll name our cluster
leaflix-east to help us know which project and region this cluster will be supporting:
That's it! Be sure to review your options one last time before clicking the "Create Cluster" button.
Atlas requires clients to authenticate as MongoDB database users to access clusters, so let's create one real quick for your cluster.
As you can see in the GIF above, creating a database user is straightforward. First navigate to the "Database Access" section (located under "Security" in the left-hand navigation bar). Click on "Create a new Database User". A prompt will appear where you can choose this user's authentication method and database user privileges.
Select the "Password" authentication method and give this user a username and password. As a convenience, you can even autogenerate a secure password right in Atlas, which we highly recommend.
💡 After autogenerating your password, be sure to click Copy and store it in a safe place for now. We'll need it later when connecting to our cluster!
Choose a built-in role for this user. For this tutorial, I'm choosing "Atlas admin" which grants the most privileges.
Finally, click the "Add User" button. You've created your cluster's first database user!
The last step in setting up your cluster is to choose which IP addresses are allowed to access it. To quickly get up and running, set your cluster to allow access from anywhere:
Congratulations! You've just successfully set up your Atlas cluster!
💡 Note: You probably don't want to allow this type of access in a production environment. Instead, you'll want to identify the exact IP addresses you know your application will be hosted on and explicitly set which IP addresses, or IP ranges, should have access to your cluster. After setting up your Heroku app, follow the steps in the "Configuring Heroku IP Addresses in Atlas" section below to see how to add the proper IP addresses for your Heroku app.
Quickly setting up our Atlas cluster was pretty exciting, but we think you'll find this section even more thrilling!
Atlas-backed, Heroku applications are simple to set up. All you need to do is create an application-level config var that holds your cluster's connection string. Once set up, you can securely access that config var within your application!
Here's how to do it:
1 heroku login
This command opens your web browser to the Heroku login page. If you're already logged in, just click the "Log in" button. Alternatively, you can use the -i flag to log in via the command line.
To continue this tutorial, I've created a demo Node application that uses MongoDB Atlas and is an app I'd like to deploy to Heroku. Clone it, then navigate to its directory:
1 git clone https://github.com/adriennetacke/mongodb-atlas-heroku-leaflix-demo.git 2 3 cd mongodb-atlas-heroku-leaflix-demo
1 heroku create leaflix
As you can see, I've named mine
leaflix.Head back to your Atlas cluster's dashboard as we'll need to grab our connection string.
Click the "Connect" button.
Choose the "Connect your application" option.
Here, you'll see the connection string we'll need to connect to our cluster. Copy the connection string.
Paste the string into an editor; we'll need to modify it a bit before we can set it to a Heroku config variable.
As you can see, Atlas has conveniently added the username of the database user we previously created. To complete the connection string and make it valid, replace the <password> with your own database user's password and
<dbname> with sample_mflix, which is the sample dataset our demo application will use.💡 If you don't have your database user's password handy, autogenerate a new one and use that in your connection string. Just remember to update it if you autogenerate it again! You can find the password by going to Database Access > Clicking "Edit" on the desired database user > Edit Password > Autogenerate Secure Password
Now that we've properly formed our connection string, it's time to store it in a Heroku config variable. Let's set our connection string to a config var called MONGODB_URI:
1 heroku config:set MONGODB_URI="mongodb+srv://yourUsername:yourPassword@yourClusterName.n9z04.mongodb.net/sample_mflix?retryWrites=true&w=majority"
Some important things to note here:
- This command is all one line.
- Since the format of our connection string contains special characters, it is necessary to wrap it within quotes.
That's all there is to it! You've now properly added your Atlas cluster's connection string as a Heroku config variable, which means you can securely access that string once your application is deployed to Heroku.
💡 Alternatively, you can also add this config var via your app's "Settings" tab in the Heroku Dashboard. Head to your apps > leaflix > Settings. Within the Config Vars section, click the "Reveal Config Vars" button, and add your config var there.
The last step is to modify your application's code to access these variables.
In our demo application, you'll see that we have hard-coded our Atlas cluster connection string. We should refactor our code to use the Heroku config variable we previously created.
Config vars are exposed to your application's code as environment variables. Accessing these variables will depend on your application's language; for example, you'd use
System.getenv('key') calls in Java or ENV['key'] calls in Ruby.Knowing this, and knowing our application is written in Node, we can access our Atlas cluster via the
process.env property, made available to us in Node.js. In the server.js file, change the uri constant to this:1 const uri = process.env.MONGODB_URI;
That's it! Since we've added our Atlas cluster connection string as a Heroku config var, our application will be able to access it securely once it's deployed.
Save that file, commit that change, then deploy your code to Heroku.
1 git commit -am "fix: refactor hard coded connection string to Heroku config var" 2 3 git push heroku master
Your app is now deployed! You can double check that at least one instance of Leaflix is running by using this command:
1 heroku ps:scale web=1
If you see a message that says
Scaling dynos... done, now running web at 1:Free, you'll know that at least one instance is up and running.Finally, go visit your app. You can do so with this useful command:
1 heroku open
If all is well, you'll see something like this:
When you click on the "Need a Laugh?" button, our app will randomly choose a movie that has the "Comedy" genre in its genres field. This comes straight from our Atlas cluster and uses the
sample_mflix dataset.We have our cluster up and running and our app is deployed to Heroku!
To get us through the tutorial, we initially configured our cluster to accept connections from any IP address. Ideally you would like to restrict access to only your application, and there are a few ways to do this on Heroku.
The first way is to use an add-on to provide a static outbound IP address for your application that you can use to restrict access in Atlas. You can find some listed here:
Another way would be to use Heroku Private Spaces and use the static outbound IPs for your space. This is a more expensive option, but does not require a separate add-on.
There are some documents and articles out there that suggest you can use IP ranges published by either AWS or Heroku to allow access to IPs originating in your AWS region or Heroku Dynos located in those regions. While this is possible, it is not recommended as those ranges are subject to change over time. Instead we recommend one of the two methods above.
Once you have the IP address(es) for your application, you can use them to configure your firewall in Atlas.
Head to your Atlas cluster, delete any existing IP ranges, then add them to your allow list:
Of course, at all times you will be communicating between your application and your Atlas database securely via TLS encryption.
We've accomplished quite a bit in a relatively short time! As a recap:
- We set up and deployed an Atlas cluster in five steps or less.
- We created a Heroku config variable to securely store our Atlas connection string, enabling us to connect our Atlas cluster to our Heroku application.
- We learned that Heroku config variables are exposed to our application's code as environment variables.
- We refactored the hard-coded URI string in our code to point to a
process.env.MONGODB_URIvariable instead.
Have additional questions or a specific use case not covered here? Head over to MongoDB Developer's Community Forums and start a discussion! We look forward to hearing from you.
And to learn more about MongoDB Atlas, check out this great Intro to MongoDB Atlas in 10 Minutes by fellow developer advocate Jesse Hall!
Rate this tutorial