Overview

In this How-To guide, we'll create a free MongoDB database at MongoDB.com, and then connect it to a simple MERN stack app (Mongo, Express, React & Node.js) that we deploy on Uffizzi. You can get the code for the app here on GitHub.

1. Setup MongoDB
2. Configure your app
3. Deploy your app to Uffizzi
4. (Optional) Whitelist connections from Uffizzi

Pre-requisites

• Add your code to GitHub (In this tutorial we'll be using a simple MERN stack app that lets you create a list of employees and stores the data in a Mongo database.)
• Create a free MongoDB account at MongoDB.com
• Create a free Uffizzi account at uffizzi.com

Setup MongoDB

1.  Create a (free) MongoDB Cluster

If this is your first time logging in to MongoDB.com, you'll see three options. Select a free Shared Cluster.

If you have logged in before, select the green Create a New Cluster button.

Next, choose your Cloud Provider & Region

For best results, select Google Cloud Platform and Iowa (us-central1).  

You can keep the default setting for the remaining options. Select Create Cluster.

2.  Add a new database user

Select Database Access from the menu on the left, then click the green Add New Database User button to the right.

3.  Create a username and password for your new database user

For Authentication Method, select Password. Enter a username and password for your database user. Don't lose this username and password—you will need them later.

4.  Configure Network Access

Configuring network access is a way to control the security of your database by limiting access to only trusted IP addresses. In this step, we'll allow connections from anywhere, and then come back later and restrict access by adding the IP address of your Uffizzi app environment. This process is known as whitelisting an IP.

Select Network Access from the menu on the left. Then select the Add IP Address button.

Next, you will see a modal pop-up. Select the ALLOW ACCESS FROM ANYWHERE button as shown in the image below. This will autofill the Access List Entry field with 0.0.0.0/0, which indicates that your database can receive connections from any IP address. You can leave the Comment field blank or enter a message to remind yourself to add your Uffizzi IP later. Click Confirm.

5.  Connect to your cluster

Select Clusters from the menu on the left, then select the CONNECT button to the right.

Next you'll be asked to choose your connection method. Here you have three options, choose the option titled Connect your application. 

Note: The third option, MongoDB Compass, is an interactive desktop application you can download for free that makes it easy to add, remove or view data stored in your database. It's a good tool to use to confirm that your application properly POSTs or GETs data to/from your database.

After selecting Connect your application, on the next page of the modal you should see a connection string that starts with:

mongodb+srv://...

Copy this connection string. We'll use it when we configure our app on Uffizzi. Notice that the string has angle bracket placeholders for <password> and <dbname>. Later, you'll replace this placeholder with the password you created earlier for your database user and the name of your cluster's database, which by default is test. 

Configure your app

We need to make some additions to server.js to ensure our application will run in the cloud. You can see the full server.js file here.

In this section we'll use environment variables to configure how our app will listen for connections and connect to our MongoDB. Environment variables are name-value pairs that are loaded into our application at runtime. They are often used to pass configuration details to an application. Environment variables are a good way to provide authentication credentials to an application without hard coding them into the application itself. Keeping configuration details out of your source code also means you can safely check your code into a git repository without publicly exposing sensitive data.

1.  Set process.env.PORT in server.js if present

We will set process.env.PORT so our application will use the HTTP port we specify in Uffizzi. We'll also add 8080 as a fallback port for our localhost development. 

const PORT = process.env.PORT || 8080;

process.env is a property that returns an object containing the user environment. So in other words, we are telling our application to use variable PORT from the environment our app is running in; otherwise, if variable PORT does not exist, use the fallback port 8080. 

2.  Set process.env.MONGODB_URI in server.js if present

We'll add environment variable MONGODB_URI and set it equal to the MongoDB connection string we copied in the previous section. However, we first need to tell our application to use this environment variable when connecting to our database. We do this by adding the following line of code to our server.js file:

mongoose.connect( process.env.MONGODB_URI || 'mongodb://localhost/my_database', {
    useNewUrlParser: true
});

Note: Your specific implementation of connecting to MongoDB may be slightly different from the above code. Here we're using mongoose, which is a MongoDB object modeling tool; however, the use of environment variables is the same for other methods.

Again, the important part here is process.envwhich, in this case, tells mongoose to connect to our database using variable MONGODB_URI from the environment our app is running in; otherwise, if variable MONGODB_URI does not exist, attempt to connect to the database on localhost. If we ran this app on our local workstation, MONGODB_URI would need to exist on our local computer; however, since we're deploying this app on Uffizzi, this environment variable will come from our Uffizzi app environment. In the next section we will add this variable to our app environment in Uffizzi so that our application can find it when we deploy.

Deploy your app to Uffizzi

1.  Create a new app environment

If this is your first time logging in to Uffizzi, you'll see welcome page. Select Get started now. If you've used Uffizzi before, navigate to the Home screen, then select Create a new environment from the My Cloud Environments section.

On the next page, you're asked to choose your app environment. Select the Free option, and then give your app environment a name, e.g. MERN Example. When you're done, click Go to next step.

2.  Import your app from GitHub

Connect your GitHub account by selecting the GitHub option in the next step. Uffizzi will open GitHub in a new window and prompt you to login. You will be asked to allow Uffizzi read access to you repositories on GitHub. Select All Repositories, then confirm. (Note: You can revoke Uffizzi's access or limit access to a specific repository at any time. In GitHub, go to Settings  >  Applications then select Configure next to Uffizzi.com.)

Once you've granted Uffizzi access to your repositories, navigate back to Uffizzi and select your MERN stack app repository from the dropdown list:

You'll be asked to confirm the branch and whether you want continuous deployments turned on. This option tells Uffizzi to automatically redeploy your application when new commits are pushed to your branch. You can leave this option turned On.

3.  Configure your app

On the next step, you're asked to configure port number and environment variables for your app. Remember MONGODB_URI? This is where we enter that environment variable.

Where it says Listens on HTTP port, keep the default port as 80. 

Where it says Environment variables, click Edit. This will bring up a modal to enter your variable.

In the NAME field, enter MONGODB_URI, and in the VALUE field enter your MongoDB connection string, being sure to replace <password> with your actual database user password and <dbname> with test. Depending on you application, you may need to enter other environment variables here. When you're done, click Save and then Go to next step.

4.  Select a database (optional)

Select Skip this step. MySQL and Postgres are managed SQL databases offered by Uffizzi. For this tutorial, we are connecting to MongoDB, which is external to Uffizzi.

5.  Review and deploy

Review your selection, and then click Deploy Now.

Next, you'll be taken to your app environment dashboard. It may take several minutes for Uffizzi to autodetect your app type, build and then deploy your app. You can view your build status in the Activity Log. Once your app is finished deploying, the OPEN APP button will be enabled. Select this button, and Uffizzi will open your app in a new tab.

You should see your application running.

We can create a new employee record and click Submit to send this data to our MongoDB instance. If you downloaded the MongoDB Compass desktop application, you can see this data in the interactive dashboard:

(Optional) Whitelist connections from Uffizzi

Now that we have our app connected to our MongoDB database, we should secure our cluster. Recall that earlier we allowed connections from any IP address. This is considered bad practice for production databases, so let's go back and tell MongoDB to only allow connections from our Uffizzi app environment. 

By default, applications hosted on Uffizzi send outbound traffic via a cloud router. This router has public IP 104.197.202.148. In the next step, we'll add this IP to MongoDB.

1.  Update your Network Access in MongoDB

From the MongoDB dashboard select Network Access again from the left side menu. To the right, you should see IP address 0.0.0.0/0 that we previously added, which allows connections from anywhere. Choose to EDIT this entry, replacing 0.0.0.0/0 with the default Uffizzi egress IP address. In my case, the IP is 104.197.202.148. Update the Comment to describe the IP you are adding, e.g. Uffizzi app environment. When you're done, click Confirm.

After a few moments you should see the status of this new IP address become Active. You will want to confirm that your app still has access to your database. In our case, we can create a new employee entry to confirm that we can still read/write to our database.

Note: If you are also using MongoDB Compass, you should add your local IP address so that your local computer can access your database as well.