Configure and Enable Atlas Device Sync
On this page
Overview
You can configure and enable Atlas Device Sync via the App Services UI, App Services CLI, or the Atlas App Services Admin API. You can update an existing configuration in the same way. If it is your first time enabling Device Sync, the UI is a great choice because it walks you through the required steps.
You might want to alter your Atlas Device Sync configuration after you have already enabled Device Sync. You can update a configuration using the same procedure as enabling Device Sync in the first place. If you're using Flexible Sync mode, you can update your configuration without needing to terminate and re-enable Sync.
If you're re-enabling Device Sync after pausing or terminating it, refer to Resume or Re-Enable Device Sync.
Tip
Device Sync pauses automatically after 30 days of inactivity.
Prerequisites
If you haven't already decided how you want to configure your data model, see Sync Data Model Overview.
Unless you are using Development Mode, you must
specify at least one valid schema for a collection in the
synced cluster before enabling Sync. At a minimum, the schema must define
_id as a primary key. You should also include the field(s) you intend to use
as your queryable fields.
For more details on how to define a schema, see Define & Enforce a Schema.
Procedure
Note
Data Source Requirements for Device Sync
To enable Device Sync, your App Services App must have at least one linked data source that meets the following requirements:
A non-sharded MongoDB Atlas cluster running MongoDB 5.0 or later.
Cluster cannot be a serverless instance or Federated database instance. Refer to Data Source Limitations.
Specify Your Sync Settings
Follow the prompts to configure Device Sync. For details on the available configuration settings, refer to Sync Settings.
Pull the Latest Version of Your App
Get a local copy of your App's configuration files. To get the latest version of your App, run the following command:
appservices pull --remote="<Your App ID>"
You can also export a copy of your application's configuration files from the UI or with the Admin API. To learn how, see Export an App.
Add a Sync Configuration
You can enable sync for a single linked cluster in your application. If you have not yet linked the cluster to your application, follow the Link a Data Source guide first.
The App Services App has a sync directory where you can find
the sync configuration file. If you have not
yet enabled Sync, this directory is empty.
Add a config.json similar to:
{ "type": "flexible", "development_mode_enabled": <Boolean>, "service_name": "<Data Source Name>", "database_name": "<Development Mode Database Name>", "state": <"enabled" | "disabled">, "client_max_offline_days": <Number>, "is_recovery_mode_disabled": <Boolean>, "indexed_queryable_fields_names": <Array of String Field Names>, "queryable_fields_names": <Array of String Field Names>, "collection_queryable_fields_names": <Map[String][]String> }
For details, refer to the Sync Configuration File Reference.
Select a Cluster to Sync
You can enable Device Sync for a single linked cluster in your application. If you have not yet linked the cluster to your application, follow the Link a Data Source guide.
Note
Authenticating Your Request with an Access Token
To authenticate your request to the App Services Admin API, you need a valid and current authorization token from the MongoDB Cloud API. Read the API Authentication documentation to learn how to acquire a valid access token.
You'll need the cluster's service configuration file to configure sync. You can find the configuration file by listing all services through the Admin API:
curl https://services.cloud.mongodb.com/api/admin/v3.0/groups/{GROUP_ID}/apps/{APP_ID}/services \ -X GET \ -h 'Authorization: Bearer <Valid Access Token>'
Identify the cluster whose configuration you need to update to enable
Sync. If you have accepted the default names when configuring
your App, this should be a cluster whose name is mongodb-atlas
and type is mongodb-atlas. You need this cluster's _id.
Now you can get the service configuration file for this cluster:
curl https://services.cloud.mongodb.com/api/admin/v3.0/groups/{GROUP_ID}/apps/{APP_ID}/services/{MongoDB_Service_ID}/config \ -X GET \ -h 'Authorization: Bearer <Valid Access Token>'
To configure Sync, we will add a flexible_sync object to this configuration in a following step.
Enable Development Mode (optional)
If you would like to enable Development Mode to streamline production, use the following command:
curl https://services.cloud.mongodb.com/api/admin/v3.0/groups/{GROUP_ID}/apps/{APP_ID}/sync/config \ -X PUT \ -h 'Authorization: Bearer <Valid Access Token>' \ -h "Content-Type: application/json" \ -d '{"development_mode_enabled": true}'
Add and Deploy the Sync Configuration
To deploy your changes and start syncing data, send an
Admin API request that updates the cluster
configuration with a
flexible_sync object using the following template configuration:
curl https://services.cloud.mongodb.com/api/admin/v3.0/groups/{GROUP_ID}/apps/{APP_ID}/services/{MongoDB_Service_ID}/config \ -X PATCH \ -h 'Authorization: Bearer <Valid Access Token>' \ -h "Content-Type: application/json" \ -d '<Flexible Sync Configuration>'
{ "flexible_sync": { "state": "enabled", "database_name": "<Name of Database>", "client_max_offline_days": <Number>, "is_recovery_mode_disabled": <Boolean>, "indexed_queryable_fields_names": <Array of String Field Names>, "queryable_fields_names": <Array of String Field Names>, "collection_queryable_fields_names": <Map[String][]String> } }
For details on the Sync configuration, refer to the Sync Configuration File Reference.
You can confirm the Sync configuration is added by getting the service configuration again, as described in Step 1.