• Realm >
• Tutorial >
• 1: Setup

Set up the Task Tracker Tutorial Backend

Overview

Before we can implement any client SDK functionality for the Task Tracker, we need to create a backend Realm app to serve SDK requests like authentication and Realm Sync. To make this easier and faster, we’ve already prepared a backend Realm app configuration for you, complete with functions, triggers, a schema, and the Realm Sync configuration you’ll need to connect with one of our front-end tutorial apps.

To use our pre-made backend, you’ll have to:

1. Create an Atlas account, if you don’t already have one. (3 minutes)
2. Create a free Atlas cluster running MongoDB 4.4. (5 minutes)
3. Install the Realm CLI. (5 minutes)
4. Add a programmatic API key to your Atlas project and use it to log into the Realm CLI. (5 minutes)
5. Use the Realm CLI to create a new Task Tracker backend Realm app with our pre-made Task Tracker backend. (5 minutes)

Once we’ve finished these steps, we can start writing code to implement a frontend using Swift, Kotlin, or JavaScript.

A. Create an Atlas Account

Time estimate: 3 minutes

To begin, you’ll need a MongoDB Atlas account. If you’ve already got an existing MongoDB Atlas Account, you can proceed to the next step. If you don’t have an Atlas account, follow the steps below to create one:

1. Navigate to the MongoDB Atlas login page.

1. Click Login.

2. Either enter a new set of user credentials or click the Sign Up with Google button.

3. Click Sign Up to create your account.

4. Follow the prompts to create an organization and project in your Atlas account. You can use the default suggested names or enter your own.

   

When you finish creating your organization and project, you should end up on a screen that prompts you to create an Atlas cluster:

See

For additional details on how to create an account, see Create an Atlas Account.

B. Create a Free Atlas Cluster

Time estimate: 5 minutes

MongoDB Version 4.4 Required

In order to use Realm Sync, your Atlas cluster must use MongoDB version 4.4. When setting up your cluster, select MongoDB 4.4 from the dropdown menu under Additional Settings.

Next, you’ll need an MongoDB Atlas cluster running MongoDB 4.4 or higher. If you’ve already created a free cluster in your Atlas project running a version of MongoDB other than 4.4, you can create a new project in Atlas and then create a new cluster running MongoDB 4.4 in that project using the instructions below. If you haven’t created any clusters yet, follow the instructions below to create your first free cluster:

1. Log into your MongoDB Atlas account at cloud.mongodb.com.

2. Once you’re logged into your account, Atlas should prompt you to create your first cluster. In the Shared Clusters category, click Create a Cluster. Alternatively, you can click Build a Cluster from the project view in your Atlas account.

   

3. Under Cloud Provider & Region, select AWS and N. Virginia (us-east-1).

4. Under Additional Settings, select MongoDB 4.4 from the Select a Version dropdown.

5. Under Cluster Name, enter the name Cluster0 for your new cluster.

6. Click the Create Cluster button at the bottom of the page.

After creating your cluster, Atlas should launch the project view for your Atlas account. In this view, you’ll see Atlas’s progress as it initializes your new cluster:

See

For additional details on how to create a MongoDB Atlas cluster, see Deploy a Free Tier Cluster.

C. Install the Realm CLI

Time estimate: 5 minutes

Now that you’ve created a cluster to use as the data source for your Realm app, we need some way to create the app itself. In most cases you’d use the Realm UI, which you can access through the Atlas UI. However, for the purposes of this tutorial, we’re going to use the Realm Command Line Interface, also known as realm-cli.

We’re using the Realm CLI because realm-cli allows you to manage your Realm apps programmatically using JSON configuration files instead of the Realm UI. This lets you get started with a pre-prepared app configuration faster. Follow the instructions below to install the Realm CLI in your development environment using either a package manager or the realm-cli binary:

• npm / Yarn
• Manual Install

The easiest way to install realm-cli is with the npm package manager. Ensure that you have Node.js installed, then run the following command in your shell:

copy

npm install -g mongodb-realm-cli

You can also install the CLI from npm with Yarn:

copy

yarn global add mongodb-realm-cli

1

Download the realm-cli binary

You can download the realm-cli binary directly from the Realm UI.

1. Navigate to the Deploy page from the left-hand navigation.
2. Select the Import/Export tab.
3. In the Download CLI Client section, select the operating system on which you want to install realm-cli. The CLI binary should begin downloading immediately.

2

Add the realm-cli binary to your system PATH

• Linux / macOS
• Windows

When you call realm-cli from the command line, your shell searches each directory listed in your PATH environment variable for the realm-cli executable binary.

Move the realm-cli binary file from your downloads folder to a directory listed in your PATH.

copy

mv /path/to/downloads/realm-cli /usr/local/bin/realm-cli

You can check which directories are listed in your PATH by running the following from the command line:

copy

echo $PATH

To add a directory to your path, add the following to the bottom of your shell rc file (e.g. ~/.bashrc), substituting in the path of the directory you’d like to add:

copy

export PATH=${PATH}:path/to/directory

When you call realm-cli.exe from the command line, your system searches each directory listed in your %PATH% environment variable for the realm-cli executable file.

Move realm-cli.exe to a directory that is listed in %PATH%.

You can check which directories are listed in %PATH% as well as add new directories from the Environment Variables configuration window. You can find this window by searching for “Environment Variables” or by following these steps:

1. Depending on which version of Windows you’re running, right click My Computer or This PC and select Properties.
2. Click Advanced Properties, then Environment Variables.

In the Environment Variables window, your PATH variable is listed under System Variables.

3

(Linux / macOS) Configure execution permissions for realm-cli

On Linux and Mac systems, no user has execution permissions for realm-cli by default. To add execution permissions, run the following command:

copy

chmod +x path/to/realm-cli

To confirm that realm-cli has execution permissions, navigate to the directory containing the binary and run the following command:

copy

ls -l | grep "realm-cli"

The output of this command should resemble the following:

-rwxrwxr-x@  1 user  staff      9443152 Mar  6 12:01 realm-cli

The ls -l command lists the file’s permissions followed by some additional information. If the permissions string in your output includes the letter x then you have successfully configured execution permissions. If no x is present (e.g. -rw-r--r--@) you did not successfully configure execution permissions and should run the chmod command as described above.

After installing the realm-cli, you can run the following command to confirm that your installation was successful:

copy

realm-cli --version

If you see output containing a version number such as 1.1.0, your realm-cli installation was successful.

See

For additional details on how to install realm-cli, see the Realm CLI installation guide.

D. Add an API Key to Your Atlas Project & Log into the Realm CLI

Time estimate: 5 minutes

Now that you’ve got realm-cli installed to your development environment, you’ll need a way to authenticate using realm-cli. For security reasons, realm-cli only allows login using a programmatic API key, so we’ll begin by creating a programmatic API Key that you can use to administrate your new Atlas project:

1. Click Access Manager at the top of the Atlas UI. Select the Project Access option from the dropdown.

2. Navigate to the API Keys tab.

3. Click the Create API Key button.

4. In the Description text box, enter “API Key for the MongoDB Realm CLI”.

   

5. In the Project Permissions dropdown, select “Project Owner” and deselect “Project Read Only”.

   

6. Copy your Public API Key and save it somewhere.

7. Click Next.

8. Copy your Private API Key and save it somewhere; after leaving this page, you will no longer be able to view it via the Realm UI.

9. Click the Add Whitelist Entry button.

10. Click Use Current IP Address.

11. Click Save.

12. When you have safely recorded your private API key, click Done to navigate back to the Project Access Manager page.

13. Use the following command in your terminal to authenticate with the Realm CLI:

    copy

    realm-cli login --api-key <public API key> --private-api-key <private API key>
    

If realm-cli produces output like the following, you have successfully authenticated:

copy

you have successfully logged in as <public API key>

See

For additional details about how to create a programmatic API key in MongoDB Atlas, see the documentation for configuring API access.

See

For additional details about authenticating using a programmatic API key with realm-cli, see the Realm CLI authentication guide.

E. Use the Realm CLI to Create a New Task Tracker Backend Realm App

Time estimate: 5 minutes

Now that you’ve got an Atlas account, an Atlas cluster running MongoDB 4.4, and an authenticated realm-cli session, you’re ready to fetch the Task Tracker backend configuration. Begin by downloading the realm-tutorial-backend github repository using the git command line tool:

1. Run the following command to download the pre-made Task Tracker backend configuration:

   copy

   git clone https://github.com/mongodb-university/realm-tutorial-backend.git
   

   You should see output like the following:

   copy

   Cloning into 'realm-tutorial-backend'...
   remote: Enumerating objects: 39, done.
   remote: Counting objects: 100% (39/39), done.
   remote: Compressing objects: 100% (31/31), done.
   remote: Total 39 (delta 3), reused 39 (delta 3), pack-reused 0
   Receiving objects: 100% (39/39), 7.25 KiB | 1.81 MiB/s, done.
   Resolving deltas: 100% (3/3), done.
   

   The directory where you ran the above git clone command should now contain another directory called realm-tutorial-backend. We’ll use the contents of that directory to create your very own Task Tracker Realm app backend with the Realm CLI.

2. Navigate into the root directory of the realm-tutorial-backend project:

   copy

   cd realm-tutorial-backend
   

3. Run the import command of realm-cli to create your app.

   copy

   realm-cli import
   

4. realm-cli may take a few seconds to query your Atlas project, but you should soon see the following output:

   copy

   this app does not exist yet: would you like to create a new app? [y/n]:
   

   Press “y”, then press ENTER to confirm your intention to create a new app.

5. realm-cli will prompt you for the following details:

   copy

   App name [tasktracker]:
   Available Projects:
   Project 0 - <project ID>
   Atlas Project Name or ID [Project 0]:
   Location [US-VA]:
   Deployment Model [GLOBAL]:
   

   Press ENTER at each prompt to use the default value for your app configuration.

If you see output containing the App ID for your new Realm app, your import command successfully created a new app:

copy

Successfully imported 'tasktracker-...'

Important

Note down this Realm app ID (“tasktracker-…”). You’ll use this Realm app ID to connect to your Realm app in the client SDK tutorials.

You can also confirm that your app was created successfully by navigating to the Realm tab in the Atlas UI. You should see a Realm app named tasktracker:

F. Verify that the Task Tracker Backend is Properly Configured

Time estimate: 5 minutes

Now that you’ve successfully created your application, it’s time to explore the provided configuration. You can access your app by navigating to the Realm tab in the Atlas UI. Click on the card representing the tasktracker app to launch the Realm UI for managing the Task Tracker backend.

Now that we can view the configuration of our app in the Realm UI, we can take a look at all of the configuration uploaded from the JSON in realm-tutorial-backend. If you’d rather jump straight into a client SDK guides, you can find the links in the What’s Next? section below.

Schema

The Schema section of the Realm UI displays information about the structure of the data stored in our linked Atlas cluster. In this section, you should see a cluster called mongodb-atlas that contains two collections: Task and User. You can navigate to the Schema tab to view the JSON Schema that defines the structure of the data in each collection.

While MongoDB’s document model allows us to store data in a wide variety of shapes and sizes, Realm Database and Realm Sync require data to follow a set schema. Data that follows this schema synchronizes between the MongoDB Atlas linked data source and devices connected to your Realm app via a client SDK. This schema should match the models defined in client applications, with minor exceptions.

See

To learn more about schemas in MongoDB Realm, see the documentation on Realm Schemas.

Authentication

In the Authentication Providers tab of the Authentication section, you’ll find information about the different ways that users can log into the Task Tracker app. In the provided Task Tracker configuration, users can only log in via “Email/Password” authentication, which lets users define an email username and a secret password known only to them to access their account in your Realm app.

If you click on the Email/Password entry in the list of authentication providers, you can view the details of Task Tracker’s Email/Password authentication configuration. There are a few important fields here:

• User Confirmation Method: we’ve selected “automatically confirm users” so that users can log in immediately after creating an account. In a production application, you might prefer to “send a confirmation email” so that users can confirm ownership of their email accounts.
• Password Reset Method: we’ve selected “run a password reset function”, but resetFunc doesn’t actually implement any logic: it always fails. For a production application, you’d want to implement a function that actually resets the user’s password if they forget it.

See

To learn more about authentication in MongoDB Realm, see the documentation on Authentication.

Sync

In the Sync section, you’ll find information about Realm Sync, which synchronizes data between client devices and your MongoDB Atlas cluster. To enable sync, we’ve define a partition key, which sorts the data in Atlas into multiple realms. We’ve chosen an easy-to-understand name for our partition key: _partition. Task Tracker also defines permissions for Realm Sync, which determine what partitions each user can access. Click the Define Permissions dropdown to view the permission definitions, which call the canReadPartition and canWritePartition functions to determine whether a user can read or write a particular realm.

See

To learn more about Realm Sync, see Get Started with Sync.

Custom User Data & Permissions

In MongoDB Realm, each user can have an associated custom data object. We designed this app to use data stored in the user’s custom data to determine permissions – that is, whether that user can read or write a given realm or set of data, such as a project. While Realm allows clients to read and write data depending on how you configure your app permissions, we configured this app so that only system functions running on the backend can modify a user’s custom data object. This prevents clients from arbitrarily granting themselves permissions.

See

To learn more about custom user data, see Enable Custom User Data.

Functions

The Functions section contains the Task Tracker app’s executable backend logic. This includes functions that:

• add a team member to a user’s project
• determine whether or not a user can read a particular partition
• determine whether or not a user can write to a particular partition
• create a new user document in the synced Atlas cluster
• fetch the members of a user’s project
• remove a team member from a user’s project
• reset a user’s password (unimplemented)

Click on any of the functions to view the JavaScript function definition. You can even run the function with test input.

See

To learn more about functions in MongoDB Realm, see the documentation on functions.

Triggers

In the Triggers section, you’ll find information about triggers, certain criteria that, when met, execute logic in the Task Tracker backend via a function. In Task Tracker, you’ll find one trigger: onNewUser. Click on the trigger to see details about the type of trigger and the function that that trigger activates. onNewUser has just one purpose: when a new user creates an account (hence the “Create” action type and the “Authentication” trigger type), onNewUser calls the createNewUserDocument function which initializes the custom user data for that user. This provides the first data needed to create that user’s personal project, and allows them to start adding to-do tasks or even other users as project members.

See

To learn more about triggers in MongoDB Realm, see the documentation on triggers.

What’s Next?

You just built a functional task tracker application backend with MongoDB Realm. Great job!

Now that you have a working Realm application, you can follow one of our client application tutorials to connect to your Realm app and manage tasks from a mobile or web application.

• iOS (Swift)
• Android (Kotlin)
• React Native (JavaScript)
• Web/GraphQL (TypeScript)
• Node

←   Create a Task Tracker App iOS Swift Tutorial  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.