Configure Edge Server - Preview

Prerequisites

Each Edge Server instance connects to a service in your Atlas project. Before you can use an Edge Server instance, you must create the relevant service, and configure an authentication provider and permissions for your Edge Server instance.

For more information, refer to Create a Service for Edge Server.

Edge Server Host Requirements

The host that runs the Edge Server instance may be an EC2 instance or other cloud server, or hardware that you provision on-site.

Install and Configure the Edge Server Instance

After creating an Edge Server Service or Device Sync Service, you must create an Edge Server instance. Each service may have many Edge Server instances. When you create an Edge Server instance, you get an installation script you can use to download a tool to install and manage the Edge Server instance, edgectl. You also get a token you can use to register the Edge Server instance. For more details, refer to Create an Edge Server Instance.

Use the installation script to set up and run the Edge Server instance on the host.

curl -s https://services.cloud.mongodb.com/edge/install.sh | bash

edgectl init --app-id="<INSERT-YOUR-APP-ID-HERE>" --platform=compose

edgectl config --insecure-disable-auth=true

Start and Stop the Edge Server

Use edgectl to start and stop the Edge Server instance.

To start all Edge Server instance containers, use the start command:

edgectl start

To stop all Edge Server instance containers, use the stop command:

edgectl stop

Check the Edge Server Status

When the Edge Server instance is running, you can see the status of the instance with:

edgectl status

This gives you information about the state of the Edge Server containers, and a detailed status for the Sync server with a breakdown of important information. It may look similar to:

{
   "mongoContainerStatus": {
      "message": "running"
   },
   "mongoDBStatus": {
      "message": "ready"
   },
   "syncServerContainerStatus": {
      "message": "running"
   },
   "syncServerStatus": {
      "message": "ACTIVE"
   },
   "syncServerDetailedStatus": {
      "version": "v0.22.3",
      "status": "ACTIVE",
      "cloud_connected": true,
      "num_local_clients": 0,
      "query": {
         "Item": "truepredicate"
      }
   }
}

The syncServerDetailedStatus contains information about the state of the Edge Server instance. This includes details about its connection to Atlas, and the clients connected to it, as follows:

Update the Edge Server Instance Configuration

You can make changes to an existing Edge Server instance using edgectl. After you change the configuration, restart the instance to apply the updates.

edgectl config --YOUR-FLAG-HERE

edgectl stop

edgectl start

Upgrade the Edge Server Version

As the Edge Server evolves, you may want to upgrade your Edge Server version to take advantage of new functionality. Additionally, an Edge Server instance must be no more than one major version behind the latest available, or it enters a FAILED state and cannot connect to Atlas.

edgectl update

edgectl config

edgectl start

edgectl clean

edgectl start

edgectl prune

Cycle the Edge Server API Key

To cycle the Edge Server API key:

edgectl config --update-registration-token=true

Specify the Edge Server's Query

If you don't specify a query, an Edge Server instance defaults to a global query of "*", which automatically syncs all data in all of the collections in your linked data source.

You can use a few arguments with the edgectl config command to specify the Edge Server instance Sync query:

• Pass a simple string query:

  edgectl config --query="Store: store_id == 42"

• Pass multiple query flags to supply queries for multiple collections:

  edgectl config --query="Person: age > 10" --query "Pet: type = 'cat'"

• Pass a path to a file containing a JSON object mapping more complex queries:

  edgectl config --query-file="/Users/my.user/edge-server/query.json"

• Pass a global query to use the same query for all collections:

  edgectl config --global-query="shouldSync == true"

Unless you're using a global query, Edge Server queries take the form of YOUR-SCHEMA-TITLE: YOUR-QUERY:

• YOUR-SCHEMA-TITLE: The title field of a schema, which typically matches the name of a collection in your database. In the event of two collections with identical names in different databases, we prepend the collection name with the database name; for example, databaseName_collectionName.

  Your linked Atlas data source may contain many collections, each with a matching schema. If you do not use the default Edge Server query "*" or a global query that syncs everything, each schema that you want to sync must have its own query.

  If you're using a template app, this is the Item collection.

• YOUR-QUERY: The query that determines which documents the Edge Server can sync with a collection. You can use Realm Query Language to define this query, with the same caveats around Flexible Sync RQL Limitations.

edgectl config --global-query="truepredicate"

edgectl config --global-query="store_id == 42"

edgectl config --query="Inventory: store_id == 42"

edgectl config --query="Project: facility_id == 42" --query "Item: priority >= 3"

edgectl config --query-file="/Users/my.user/edge-server/query.json"

{
  "Project": "facility_id == 42",
  "Item": "priority >= 3"
}

Simulate Offline Connectivity

Edge Server provides a demo mode you can use to simulate an Edge Server instance losing connectivity with Atlas. While the Edge Server instance is in offline demo mode, you can continue to perform CRUD operations with the instance using a MongoDB Driver or tool, or an Atlas Device SDK application.

You can see the data change locally with clients connected to the Edge Server instance, but do not see the changes reflected in Atlas. Similarly, changes that you make in Atlas while the Edge Server instance is offline do not sync to the Edge Server and reflect on local clients.

When you bring the Edge Server instance out of offline demo mode, it automatically resumes syncing with Atlas. You can see the data from the Edge Server instance reflected in Atlas, and data changed in Atlas becomes visible to the instance and connected clients.

edgectl config --insecure-enable-offline-demo

edgectl offline-demo disable-connection

edgectl offline-demo enable-connection

Run Multiple Edge Server Instances on a Host

While your Edge Server architecture is in development, you may want to run multiple Edge Server instances on a single host - for example, your local machine. You can do this using the edgectl profile functionality.

When you create an Edge Server instance, edgectl automatically creates a default profile for you. The profile maps your commands to a specific Edge Server instance.

When you create a new Edge Server instance on the same machine, edgectl sets the new profile as the default profile. To issue a command that uses a profile other than the default, add the --profile flag with each command.

edgectl start --profile=YOUR-PROFILE-NAME

You can view the profiles, and their associated configuration files, in:

~/.mongodb-edge/profiles/

edgectl init --app-id="YOUR-APP-ID" --platform=compose --profile=YOUR-PROFILE-NAME

edgectl profile list

edgectl profile inspect YOUR-PROFILE-NAME

{
  "appId" : "YOUR-APP-ID",
  "platform" : "compose"
}

edgectl profile set-default YOUR-PROFILE-NAME

edgectl profile delete YOUR-PROFILE-NAME