Docs Menu
Docs Home
/ /
Atlas App Services
/

Configure Edge Server

On this page

  • Prerequisites
  • Edge Server Host Requirements
  • Install and Configure the Edge Server Instance
  • Start and Stop the Edge Server
  • Check the Edge Server Status
  • Update the Edge Server Instance Configuration
  • Upgrade the Edge Server Version
  • Cycle the Edge Server API Key
  • Specify the Edge Server's Query
  • Simulate Offline Connectivity
  • Run Multiple Edge Server Instances on a Host

After you create an Edge Server instance in Atlas, you must configure the hardware that runs the Edge Server instance. For most use cases, you'll provision hardware on-premises to host the Edge Server instance. While you're developing your Edge Server application, you may host it on a cloud server for convenience.

Client devices on-prem connect to the Edge Server instance. Your instance connects to the Edge Server Service or Device Sync Service, depending on how you create it. Clients do not connect to MongoDB Atlas directly.

Architecture diagram showing devices connected to an Edge Server, which is connected to Atlas

This page details how to configure and perform operations on the Edge Server instance.

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.

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

Tip

For proof-of-concept testing, you can launch an EC2 instance running Ubuntu Server 18.x. Under Network settings, add a rule to allow access via HTTP/Port 80. Free tier settings are sufficient for small PoC projects.

The current minimum hardware requirements to run an Edge Server instance are:

  • CPU: 64-bit, quad-core processor

  • RAM: 8GB memory

  • Storage: 32GB disk space

These requirements may change after Edge Server benchmarking is complete.

Edge Server has been verified with the following operating systems:

  • macOS 11.x and newer running on M1 or Intel 2018+ MacBook Pros

  • Raspberry Pi OS 12

  • Ubuntu Server 18+

Other operating systems may be possible, but have not yet been verified.

For convenience, you can manage an Edge Server instance with Docker in Swarm mode during development. In production environments, use Kubernetes to manage your Edge Server containers.

If you do not have Docker installed and Swarm enabled, you will be prompted to resolve these dependencies prior to running the Edge Server.

To accept connections from sync clients or connections using a MongoDB URI, the host that runs the Edge Server must allow access to incoming connections.

If you run the Edge Server on your own infrastructure, you don't need to open the instance to the general internet. You only need to ensure your client devices can access it.

For cloud infrastructure, such as running a development environment on EC2, you must open ports to accept incoming connections:

  • Development: Use HTTP on port 80 for simplicity and speed of development.

  • Production: Use SSL with port 443 to secure access to production data.

Edge Server supports TLS.

We recommend setting up TLS termination for HTTP access, including Device SDK traffic, through a Kubernetes controller.

Connections through MongoDB URIs can configure TLS through edgectl.

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.

Important

Stop the Edge Server When Not In Use

After you start the Edge Server instance, it attempts to maintain a websocket connection to Atlas to remain in sync, even if no client application is connected. If you are running a demo or otherwise working on a PoC, remember to stop the Edge Server instance using edgectl stop when you're done using it. Otherwise, you'll continue using the host's compute and Device Sync time.

1

Edge Server uses a command-line tool called edgectl to manage the Edge Server instance on the host hardware. This includes an install script to manage the installation and install required dependencies.

Use this command to install the command-line tool and the Edge Server code on the device where you want to run the Edge Server instance:

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

Follow the prompts to download and install the Edge Server code.

2

Use edgectl to set up the Edge Server instance.

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

The minimum required parameters are the app-id and the platform.

  • --app-id: Provide your Edge Server App ID. For example, --app-id="edge-server-vtoyh". For more information, refer to Find Your App ID.

  • --platform: You can use Docker Compose to install and manage your Edge Server instance in a development environment, or Kubernetes to manage the instance in a production environment. Valid values are either compose or kubernetes.

You can provide the following optional flags to specify additional configuration details:

Field name
Type
Value
--edge-root-dir
String
The location on disk to store configuration files. Defaults to ~/.mongodb-edge/. If you specify an alternate location, you must pass this flag with the alternate location with every subsequent edgectl command you issue.
--query
String
The query that defines what data to sync between the Edge Server instance and Atlas. If you do not provide a query, the instance syncs all data that it has permissions to access. For information about populating a query, refer to Specify the Edge Server's Query.
--global-query
String
A query that applies to all collections in the linked data source. For more information, refer to Specify the Edge Server's Query.
--query-file
String
Pass a path to a JSON file that contains queries for the collections in the linked data source. For more information, refer to Specify the Edge Server's Query.
--http-port
Int
The port on which the instance listens for HTTP connections. The default value is 80.
--wire-protocol-port
Int
The port on which the instance listens for MongoDB Wire Protocol connections, such as connections from a MongoDB Driver. The default value is 27021.
--insecure-disable-auth
Boolean
If true, users can connect anonymously to the instance through Wire Protocol or Atlas Device SDK clients. Defaults to false.
--skip-user-prompt
Boolean
If true, Edge Server does not prompt for user creation. If false, Edge Server connects to Atlas to check if an email/password user exists in the service. If a corresponding email/password user does not exist, it interactively prompts for a username and password to create a user. Defaults to false.
--disable-local-ui
Boolean
If true, the Edge Server instance does not run a UI on the registered http-port. Defaults to false.
--profile
String
The name of the profile to use when executing a given edgectl command. If you do not provide a name, the profile name defaults to the app-id, with an incrementing number appended, starting with -01. When you do not provide a profile flag, edgectl uses the default profile when executing a command. For more information, refer to Run Multiple Edge Server Instances on a Host.
--registration-token
String
The one-time use registration token for the Edge Server instance. If you do not pass this flag with the token, edgectl interactively prompts for the token during initial set up.
3

When first configuring the Edge Server instance, you're prompted to supply the Edge Server token. This is the token you got when you added the instance to your service.

If you no longer have the token, you can generate a new token from the Edge Server Instance Details in your service.

The Edge Server instance exchanges this token for a secret. It uses the secret to authenticate with Atlas when it syncs data.

4

If you'd like to connect to the Edge Server instance using a MongoDB Driver or tool, you must have a username/password credential, or bypass authentication. If you already have a username/password credential, or don't plan to connect to the Edge Server instance using a MongoDB Driver or tool, you can skip this step.

For more information, refer to Connect to the Edge Server with MongoDB Drivers and Tools.

If you don't already have a username/password credential, you can create one by following the prompts during edgectl init.

Otherwise, you can manually Create an Email/Password User later using the App Services UI, the App Services CLI, or the App Services Admin API.

Alternately, if you plan to implement an authorization flow later, you can bypass authorization with the following command and flag:

edgectl config --insecure-disable-auth=true

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

Important

Stop the Edge Server When Not In Use

After you start the Edge Server instance, it attempts to maintain a websocket connection to Atlas to remain in sync, even if no client application is connected. If you are running a demo or otherwise working on a PoC, remember to stop the Edge Server instance using edgectl stop when you're done using it. Otherwise, you'll continue using the host's compute and Device Sync time.

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:

Field name
Type
Value
version
String
The current version of the Edge Server code that the instance is running. If the Edge Server instance falls more than one major version behind the latest available version, it is unable to connect to Atlas and must be wiped and updated. For more information, refer to Upgrade the Edge Server Version.
status
String

The current status of the Edge Server instance. Possible values include: "ACTIVE", "FAILED", and "BOOTSTRAPPING".

"ACTIVE": the instance is running, listening for connections, and attempting to sync.

"FAILED": the instance has encountered an error condition that requires intervention. For more information, refer to Troubleshoot an Edge Server Instance.

"BOOTSTRAPPING": the instance is performing an initial download of the relevant documents in the data set, and is not yet ready to use.

cloud_connected
Boolean
If true, the Edge Server instance is currently connected to Atlas. If false, the Edge Server instance is not connected to Atlas. When the instance is not connected to Atlas, it can still receive local connections and sync data with local clients. When it reconnects with Atlas, it attempts to sync data that changed while it was not connected.
num_local_clients
Int
The number of clients that are currently connected to the Edge Server instance through Atlas Device SDK. This does not include connections through the Wire Protocol.
query
Object
The Edge Server instance Sync query, presented as a JSON object. For more information, refer to Specify the Edge Server's Query.

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

1

Use the edgectl config command with the appropriate flags to update the instance:

edgectl config --YOUR-FLAG-HERE
Field name
Type
Value
--edge-root-dir
String
The location on disk to store configuration files. Defaults to ~/.mongodb-edge/. If you supplied an alternate location during initial set up, you must pass this flag with the alternate command with every edgectl command you issue.
--query
String
The query that defines what data to sync between the Edge Server instance and Atlas. If you do not provide a query, the instance syncs all data that it has permissions to access. For information about populating a query, refer to Specify the Edge Server's Query.
--global-query
String
A query that applies to all collections in the linked data source. For more information, refer to Specify the Edge Server's Query.
--query-file
String
Pass a path to a JSON file that contains queries for the collections in the linked data source. For more information, refer to Specify the Edge Server's Query.
--http-port
Int
The port on which the instance listens for HTTP connections. The default value is 80.
--wire-protocol-port
Int
The port on which the instance listens for MongoDB Wire Protocol connections, such as connections from a MongoDB Driver. The default value is 27021.
--insecure-disable-auth
Boolean
If true, users can connect anonymously to the instance through Wire Protocol or Atlas Device SDK clients. Defaults to false.
--skip-user-prompt
Boolean
If true, Edge Server does not prompt for user creation. If false, Edge Server connects to Atlas to check if an email/password user exists in the service. If a corresponding email/password user does not exist, it interactively prompts for a username and password to create a user. Defaults to false.
--disable-local-ui
Boolean
If true, the Edge Server instance does not run a UI on the registered http-port. Defaults to false.
--profile
String
The name of the profile to use when executing a given edgectl command. If you do not provide a name, the profile name defaults to the app-id, with an incrementing number appended, starting with -01. When you do not provide a profile flag, edgectl uses the default profile when executing a command. For more information, refer to Run Multiple Edge Server Instances on a Host.
--registration-token
String
A one-time use registration token for the Edge Server instance. You can pass the flag with this token to prompt the Edge Server instance to update its API key.
--update-registration-token
Boolean
Prompt edgectl to interactively request a new one-time use registration token. When you supply the new token, the Edge Server instance updates its API key.
2

After you update the configuration, stop the instance:

edgectl stop

And start it again to apply the updates:

edgectl start

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.

Important

Required network access

To upgrade the Edge Server version, edgectl must have network access. You cannot upgrade the Edge Server version if edgectl is not online.

1

You can upgrade the Edge Server version using edgectl:

edgectl update

Depending on your hardware and network connection, the upgrade process may take seconds to minutes.

You can optionally specify arguments to upgrade to a specific version:

Field name
Type
Value
--config-path
String
The location on disk to store configuration files. Defaults to ~/.mongodb-edge/.
--minor
Boolean
Upgrade to the latest minor version for your current major version. Defaults to true.
--major
Boolean
Upgrade to the next major version. Defaults to false.
--to
String
Upgrade (or downgrade) to an exact version. Default "".
2

After upgrading, edgectl prompts you to update the configuration.

edgectl config
3

After upgrading, run the Edge Server to deploy the updates.

edgectl start
4

If you encounter unexpected behavior after upgrading the Edge Server, you may want to reset it and start it again. Run the following command:

edgectl clean

Then, run the Edge Server again.

edgectl start
5

After upgrading, you can remove any files that are no longer needed.

edgectl prune

To cycle the Edge Server API key:

1

You can generate a new Edge Server token from the Edge Server Instance Details. Use the Regenerate Token button to get a new token, and copy it. You won't be able to see this token again, and must generate a new token if you do not copy it.

2

Use edgectl to be prompted for a new token from the Edge Server instance:

edgectl config --update-registration-token=true

This triggers edgectl to prompt you for the token. When you provide it, the Edge Server instance exchanges this token for a secret. It uses the secret to authenticate with Atlas when it syncs data.

Important

Required network access

To exchange the token for an API key, edgectl must have network access. You cannot cycle the API key if edgectl is not online.

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.

Note

Queryable Fields

Because Edge Servers use Device Sync to sync data with Atlas, the query you use on the Edge Server instance must use a queryable field. If you use an Edge Server Service, we automatically add fields that you use in Edge Server instance queries to the queryable fields. If you use a Device Sync Service with Edge Servers, we only add queryable fields when Development Mode is enabled.

For more information, refer to Queryable Fields.

You can sync all documents between Edge Server instance and Atlas. This uses the truepredicate or "*" query. Because this is a global query, you can pass it as a string with the edgectl --global-query argument.

If you do not provide a query when you configure your Edge Server instance, this is the default query.

edgectl config --global-query="truepredicate"

You might only want to sync a subset of documents with an Edge Server instance. For example, for an instance located in a specific store, you might want to sync only the documents relevant to that store. An RQL query for that might look similar to:

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

If the data source linked to your Edge Server-compatible service contains more than one collection, and you want to define a query for a specific collection, you can provide a mapping of the schema title for the collection, and a relevant query.

In this example, we set a query for the Inventory collection, whose schema title is also Inventory. The Edge Server instance only syncs documents from that collection where store_id matches 42, which is the store number where the Edge Server instance is located.

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

The linked data source also contains a Customers collection. But since there is no query from the Edge Server instance for that collection, none of the documents in the collection sync to the Edge Server instance - even if they contain a store_id field whose value matches the 42 from the Edge Server query.

For a more complex query, where you want to pass different queries for multiple collections, you have two options:

  • Pass multiple --query flags, one for each collection

  • Pass a path to a file where you define the queries as JSON

In these examples, we have three collections: Project, Item, and Team, whose collection names match their schema titles. These queries sync data with two of the collections: Item and Project. The Project collection has a list property that represents a to-many relationship to the Item collection. We don't want to sync the Team collection to the Edge Server instance. By omitting this schema title from the queries, we don't sync any of its data to the instance.

With these queries, we are only syncing Project documents for facility 42. Additionally, we are only syncing Item documents where the priority field's value is greater than or equal to 3. In this way, you can combine queries to sync only the documents that are relevant to a given Edge Server instance.

You can pass multiple query flags with edgectl config to provide queries for multiple collections.

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

You can pass a path to a JSON file that defines many different queries. For example:

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

Where the JSON file contains:

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

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.

Use the following edgectl flag with either the init command or the config command to set up offline demo functionality:

edgectl config --insecure-enable-offline-demo

If you issue this flag with the edgectl config command, you must restart the Edge Server instance for the change to take effect.

Before you can simulate offline connectivity, the Edge Server instance must successfully connect to Atlas. You cannot use this functionality with an Edge Server instance that has never performed an initial sync with Atlas.

After you have set up offline demo mode and successfully connected to Atlas, issue the following edgectl command to simulate offline connectivity:

edgectl offline-demo disable-connection

You get a message indicating that the internet connection has been successfully disabled. If you check the Edge Server instance status, the cloud_connected bool changes from true to false.

You can now perform CRUD operations with the Edge Server instance locally, and should not see the changes reflected in Atlas.

To simulate reconnecting to the network, issue the following edgectl command:

edgectl offline-demo enable-connection

You get a message indicating that the internet connection has been successfully enabled. If you check the Edge Server instance status, the cloud_connected bool changes from false to true.

After waiting a moment for any changes to sync, you can see local changes reflected in Atlas, and Atlas changes reflected on the Edge Server instance.

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/

You can name a profile with the --profile flag when you issue the edgectl init command:

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

You can list all profiles, and see which is currently set as the default, with the following edgectl command:

edgectl profile list

You can get details about a profile with the following edgectl command:

edgectl profile inspect YOUR-PROFILE-NAME

This provides information about the App ID and platform associated with the profile:

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

When you create a new profile, it becomes the default profile. You can set a different default profile with the following edgectl command:

edgectl profile set-default YOUR-PROFILE-NAME

If you list all profiles again, you can see the new default.

You can delete a profile with the following edgectl command:

edgectl profile delete YOUR-PROFILE-NAME

If you delete the default profile, you must either set a new default profile, or pass the --profile flag with every command you issue.

← Manage Edge Servers