A backend MongoDB Realm example application for allowing users to see location and movement of their own devices or those of people in the same private group.
The Realm React Native frontend can be found here.
To get a better overview of the implementation as well as the RealmDB data modeling, partitions, and permissions, see Diagrams.
You can import the ready-made MongoDB Realm backend using the mongodb-realm-cli, which you can install with npm:
npm install -g mongodb-realm-cliTo have a backend for your FindOurDevices app, you will need a MongoDB Atlas cluster with MongoDB 4.4 or higher. To create an Atlas account, project, and cluster, visit the Atlas UI.
⚠️ Sync requires MongoDB 4.4 or above. Be sure to select at least MongoDB version 4.4 when building your cluster!
To authenticate with the realm-cli, you must create an API key with Project Owner permissions for your project in the Project Access Manager view. Click the Access Manager at the top of the Atlas view to find it. Please follow the instructions on the MongoDB documentation site for more information.
Once created, pass the API keys to realm-cli login to log in:
realm-cli login --api-key=[public API key] --private-api-key=[private API key]- Clone the repo if you have not already done so:
# using https
git clone https://github.com/realm/FindOurDevices-backend.git
# using ssh
git clone git@github.com:realm/FindOurDevices-backend.git- In
/data_sources/mongodb-atlas/config.json, add the name of the MongoDB cluster you set up in Step 2 to theconfig.clusterNamefield. (The default name when setting it up in Atlas isCluster0.)
{
"name": "mongodb-atlas",
"type": "mongodb-atlas",
"config": {
"clusterName": "[name of MongoDB cluster]",
"readPreference": "primary",
"wireProtocolEnabled": false
},
"version": 1
}-
In
realm_config.json, verify that there is not anapp_idfield. (This will be set once the app has been imported in the next step.) -
Optionally, enable development mode to streamline schema design. (Not suitable for production.) In your Realm Sync configuration
/sync/config.json, setdevelopment_mode_enabledtotrue.
{
"state": "enabled",
"database_name": "findourdevices",
"partition": {
...
},
"development_mode_enabled": true,
"service_name": "mongodb-atlas"
}If logged in successfully, you can now import the app:
cd FindOurDevices-backend
realm-cli pushFollow the prompts and wait for the app to deploy (hit Enter to accept the suggested values).
Congratulations! You now have a working MongoDB Realm backend with Sync enabled.
If you want to make changes to the backend via your local code (using realm-cli push), the Realm App ID must first be specified in realm_config.json. Otherwise, it will ask if you want to create a new Realm app.
Copy the Realm App ID from the MongoDB Realm UI.
You can either manually add the ID before pushing any changes:
{
"config_version": 20210101,
"app_id": "[Realm App ID]",
"name": "findourdevices",
"location": "US-VA",
"deployment_model": "LOCAL",
"environment": "development"
}..or export the latest version of the Realm app to your local directory (the app_id field and value will be added to the configuration file):
realm-cli pull --remote [Realm App ID]A great help when troubleshooting is to look at the log of the app in the MongoDB Realm UI under Manage > Logs in the sidebar.
When developing and modifying schemas or making changes to documents directly in MongoDB Atlas, you may experience issues syncing the modfied object if the changes do not conform to your Realm data model. Realm Sync only propagates valid objects without throwing any errors if any of the objects do not conform to your schema/model.
Make sure to check that all expected fields and types exist on the object/document.
Some issues may also be related to permissions (see Permission errors).
The first time you import your backend Realm app to MongoDB Realm, some triggers may not get enabled. Go to the MongoDB Realm UI then navigate to Build > Triggers in the sidebar. Enable any trigger that is not currently enabled.
Also make sure the trigger is configured correctly on the backend. Trigger configurations contain a match field where you may specify when the trigger should fire using the MongoDB query language.
When developing, if you notice from looking at the logs in the MongoDB Realm UI that a trigger is fired but the function that the trigger is supposed to call is not called, you may be using a device with an IP-address that is not listed on the access list of the API key (see Permission errors).
When the Realm backend was set up, you had to add your IP to the Realm CLI API key access list. If you develop from another device or using a different network connection (or other reasons), your IP address will be different.
To edit the access list, navigate to Access Mananger > Project Access > API Keys at the top of the MongoDB Atlas UI and choose which of your keys to edit.
The diagrams presented and the notes therein provide insights into ways of thinking about RealmDB data modeling, partitioning, and permissions.
FindOurDevices uses a synced cluster with only synced realms. Data access rules and permissions are different for non-synced realms which provide document-level and field-level rules.
An Entity Relationship diagram of the FindOurDevices data model showing all Realm objects and their relationships.
Data modeling in Realm.
Potential problems that you may run into when modeling data and referencing objects, as well as various solutions for circumventing the issue and what solution FindOurDevices uses.
Partitioning in Realm.
A comparison of the permissions of two different applications (one being FindOurDevices) for the part of the app that uses a shared realm. It explains why the synced permission rules for FindOurDevices are not the same (i.e. does not allow “write” permission).
Partitions and permissions for synced realms.
Explanation of permission related issues of an earlier data model version of FindOurDevices and how a remodel solved the issue.
Partitions and permissions for synced realms and how to spot a similar weakness in your data model.
Illustration of how Realm is integrated in FindOurDevices (for the use case of having groups) and from what exact places of the data model the data on various screens come from. It also shows what Realm-related operations are performed when the user interacts with the screen.
Realm integration, denormalization, and opening/closing of realms.
Illustration of what activities happen and how the data flows when the main use case of the app occurs (i.e. a device moves X meters and the new location can be seen on the map by the user and any group members that the user is a part of). All activities within a specific column in the diagram represent what happens on that specific entity (e.g. on John’s phone, Mary’s phone, or on the MongoDB Realm backend).
Realm integration, Realm Sync, partitioning, and change listeners.
