Application Configuration Files¶
Overview¶
MongoDB Realm uses JSON files and source code files to define and configure every component of an application. Each component has a specific configuration file schema and every application uses a standard file structure to organize the configuration files.
When Will I Use Configuration Files?¶
Every Realm app is composed of a collection of configuration files, so you use application configuration files whenever you create or modify a Realm app. If you use the Realm UI then you rarely deal directly with the configuration files themselves, but other deployment methods, like Realm CLI and GitHub allow you to define and edit the configuration files directly.
Directory Structure¶
The following figure shows a high-level view of a Realm app's directory structure:
yourRealmApp/ ├── config.json ├── secrets.json ├── auth_providers/ │ └── <provider name>.json ├── functions/ │ └── <function name>/ │ ├── config.json │ └── source.js ├── services/ │ └── <service name>/ │ ├── config.json │ ├── incoming_webhooks/ │ │ ├── config.json │ │ └── source.js │ └── rules/ │ └── <rule name>.json ├── triggers/ │ └── <trigger name>.json ├── hosting/ │ ├── metadata.json │ └── files/ │ └── <files to host> └── values/ └── <value name>.json
Application Configuration¶
Application-level configuration information is defined in a single
document named config.json
stored in your application's root
directory.
yourRealmApp/ └── config.json
Configuration¶
{ "app_id": "", "name": "", "security": { "allowed_request_origins": ["<Origin URL>"] }, "hosting": { "enabled": <boolean>, "custom_domain": "<Custom Domain Name>", "app_default_domain": "<Default Domain Name>" }, "custom_user_data_config": { "enabled": <Boolean> "mongo_service_id": "<MongoDB Service ID>", "database_name": "<Database Name>", "collection_name": "<Collection Name>", "user_id_field": "<Field Name>" } "deployment_model": "<Deployment Model Type>", "location": "<Deployment Cloud Region Name>", "config_version": <Version Number>
}
Field | Description | |||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
app_id String | The application's App ID. | |||||||||||||||||||
name String | The application's name. Note App Name Limitations Application names must be between 1 and 32 characters and may only contain ASCII letters, numbers, underscores, and hyphens. | |||||||||||||||||||
security Document | A document that contains configuration options for application-level security features.
| |||||||||||||||||||
hosting Document | A document that contains configuration options for all hosted files:
| |||||||||||||||||||
config_version Number | The schema version that all configuration files in the application conform to. This value is machine generated and you typically should not manually set or modify it. | |||||||||||||||||||
custom_user_data_config Document | A document that contains configuration options for custom user data.
| |||||||||||||||||||
deployment_model String | The application's deployment model. The following values are valid:
| |||||||||||||||||||
location String | The name of the cloud region that the application is deployed in.
|
Authentication Providers¶
Authentication providers
are defined in your application's /auth_providers
directory.
Each provider is defined in its own JSON file named after the provider. For detailed information on configuring and using a specific authentication provider, see that provider's reference page.
yourRealmApp/ └── auth_providers/ └── <provider name>.json
Configuration¶
{ "id": "<Provider ID>", "name": "<Provider Name>", "type": "<Provider Type>", "disabled": <Boolean>, "config": { "<Configuration Option>": <Configuration Value> }, "secret_config": { "<Configuration Option>": "<Secret Name>" }, "metadata_fields": [{ "required": <Boolean>, "name": "Field Name" }] }
Field | Description |
---|---|
id String | A value that uniquely identifies the authentication provider. Realm automatically generates a unique ID for a provider when you create it. |
name String | The name of the authentication provider. |
type String | The type of the authentication provider. Valid Options:
|
config Document | A document that contains configuration values that are specific to the authentication provider. The existence of this field and its exact configuration fields depend on the provider type. |
secret_config Document | A document where each field name is a private configuration field for the provider and the value of each field is the name of a Secret that stores the configuration value. |
metadata_fields Array<Document> | An array of documents where each document defines a metadata field that describes the user. The existence of this field and the exact format of each metadata field document depends on the provider type. |
disabled Boolean | If true , this authentication provider is not enabled for your
application and cannot be used. |
Functions¶
Realm Functions are defined in a sub-directory of your application's
/functions
directory. Each function maps to its own subdirectory
with the same name as the function.
Each function is configured in config.json
and has its source code
defined in source.js
.
yourRealmApp/ └── functions/ └── <function name>/ ├── config.json └── source.js
Configuration¶
{ "id": "<Function ID>", "name": "<Function Name>", "private": <Boolean>, "can_evaluate": <Rule Expression>, "disable_arg_logs": <Boolean>, "run_as_system": <Boolean>, "run_as_user_id": "<Realm User ID>", "run_as_user_id_script_source": "<Function Source Code>" }
Field | Description |
---|---|
id String | A value that uniquely identifies the function. Realm automatically generates a unique ID for a function when you create it. |
name String | The name of the function. The name must be unique among all functions in your application. |
private Boolean | If true , this function may only be accessed from incoming
webhooks, rules, and named functions. |
can_evaluate Document | A rule expression that
evaluates to true when the function is allowed to execute in
response to a given request. |
disable_arg_logs Boolean | If true , Realm omits the arguments provided to a function
from the function execution log entry. |
run_as_system Boolean | If true , this function runs as the system user. This overrides any values defined for
run_as_user_id and run_as_user_id_script_source . |
run_as_user_id String | The unique ID of a Realm User that the
function always executes as. Cannot be used with
run_as_user_id_script_source . |
run_as_user_id_script_source String | A stringified function that runs whenever the
function is called and returns the unique ID of a Realm
User that the function executes as. Cannot be used with
run_as_user_id . |
Source Code¶
exports = function() { // function code };
MongoDB Services¶
Every MongoDB Atlas data source
linked to your app is configured as a service in the /services
directory. Each data source maps to its own sub-directory with the same
name as the service.
The primary service configuration for a MongoDB Atlas data source is
config.json
, which defines connection parameters and sync rules.
If the data source is not a synced cluster or Data
Lake, then you can define collection-level rules in
the /rules
sub-directory.
yourRealmApp/ └── services/ └── <MongoDB Service Name>/ ├── config.json └── rules/ └── <rule name>.json
MongoDB Service names are not necessarily the same as their linked
data source's name in Atlas. You define the service name for a data
source when you link it to your application. For linked clusters, the
default MongoDB service name is mongodb-atlas
. For linked Data
Lakes, the default service name is mongodb-datalake
.
Service Configuration¶
The configuration file to link an Atlas cluster should have the following form:
{ "id": "<Service ID>", "name": "<Service Name>", "type": "mongodb-atlas", "config": { "clusterName": "<Atlas Cluster Name>", "readPreference": "<Read Preference>", "wireProtocolEnabled": <Boolean>, "sync": <Sync Configuration> } }
The configuration file to link a Data Lake should have the following form:
{ "id": "<Service ID>", "name": "<Service Name>", "type": "datalake", "config": { "dataLakeName": "<Data Lake>" } }
Exactly one of config.dataLakeName
and config.clusterName
is
required, depending on whether you are linking a Data Lake or a cluster.
Field | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id String | A string that uniquely identifies the service. Realm automatically generates a unique ID for a MongoDB service when you create it. | ||||||||||||
name String | The name of the service. The name may be at most 64 characters
long and can only contain ASCII letters, numbers, underscores,
and hyphens. For clusters, the default name is mongodb-atlas .
For Data Lakes, it is mongodb-datalake . | ||||||||||||
type String | For MongoDB Atlas clusters, this value is always "mongodb-atlas" .
For Data Lakes, this value is "datalake" . | ||||||||||||
config.clusterName String | Required when linking a cluster. The name of the service's linked cluster in MongoDB Atlas. | ||||||||||||
config.dataLakeName String | Required when linking a Data Lake. The name of the Data Lake that you want to link to your application. | ||||||||||||
config.readPreference String | The read preference mode for queries sent through the service. Not available for Data Lakes.
| ||||||||||||
config.sync Document | A configuration document that determines if a cluster is synced and, if it is, defines the rules for sync operations on the cluster. Not available for Data Lakes. For detailed information on sync configuration documents, see Synced Cluster Configuration. |
Synced Cluster Configuration¶
The config.sync
field of config.json
determines if a cluster is
synced and, if it is, defines the rules for sync operations on
the cluster.
{ ..., "config": { ..., "sync": { "state": <Boolean>, "development_mode_enabled": <Boolean>, "database_name": "<Developer Mode Database Name>", "partition": { "key": "<Partition Key Field Name>", "type": "<Partition Key Value Type>", "permissions": { "read": <JSON Expression>, "write": <JSON Expression> } } } } }
Field | Description |
---|---|
sync.state Boolean | If true , Sync is enabled for the cluster, which means
that client applications can sync data in the cluster with Realm Database
and that non-sync collection rules do not
apply. |
sync.development_mode_enabled Boolean | If true , development mode is enabled for the cluster. While
enabled, Realm does not enforce sync rules, stores synced objects in a
specific database within the cluster, and mirrors object types in that
database's collection schemas. |
sync.database_name String | The name of the database in the synced cluster where Realm should store synced objects. When development mode is enabled, Realm stores synced objects in this database. Each object type maps to its own collection in the database with a schema that matches the synced objects. |
sync.partition.key String | The name of the field that partitions data into client Realms. |
sync.partition.type String | The type of the partition key field value. |
sync.partition.permissions Document | A document that defines the read and write permissions for the
synced cluster. Permissions are defined with rule expressions that Realm evaluates per-user, per-partition. The
expressions have access to the %%user and
%%partition expansions. |
MongoDB Collection Rules (Non-Sync)¶
For non-synced clusters, you can define collection-level rules that Realm
evaluates dynamically for each request. Each collection's rules are stored in
the /rules
sub-directory in a JSON file with the same name as the collection
namespace.
Data Lake data sources do not support rules. You can only access a Data Lake data source in a system function.
{ "id": "<Rule ID>", "database": "<Database Name>", "collection": "<Collection Name>", "roles": [<Query Role>], "schema": <Document Schema>, "filters": [<Query Filter>], }
Field | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id String | A string that uniquely identifies the trigger. Realm automatically generates a unique ID for a trigger when you create it. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
database String | The name of the database that holds the collection. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
collection String | The name of the collection. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
roles Array<Document> | An array of Query Role configuration documents, which have the following form:
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
schema Document | A Document Schema. The root level schema must be an object schema, which has the following form:
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
filters Array<Document> | An array of Query Filter configuration documents, which have the following form:
|
External Services¶
3rd party services are defined in the /services
directory. Each service maps to its own sub-directory with the same name as the
service.
Each service directory contains the following:
config.json
: a service configuration file/rules
: a sub-directory of service rule configurations/incoming_webhooks
: a sub-directory of webhook configurations (if the service supports webhooks, i.e. HTTP, GitHub, or Twilio)
yourRealmApp/ └── services/ └── <services name>/ ├── config.json ├── incoming_webhooks/ │ ├── config.json │ └── source.js └── rules/ └── <rule name>.json
Service Configuration¶
{ "id": "<Service ID>", "name": "<Service Name>", "type": "<Service Type>", "config": { "<Configuration Option>": <Configuration Value> }, "secret_config": { "<Configuration Option>": "<Secret Name>" }, }
Field | Description |
---|---|
id String | A string that uniquely identifies the service. Realm automatically generates a unique ID for a service when you create it. |
name String | The name of the service. The name may be at most 64 characters long and can only contain ASCII letters, numbers, underscores, and hyphens. |
type String | The type of the service. Valid Options:
|
config Document | A document with fields that map to additional configuration
options for the service. The exact configuration fields depend on
the service |
secret_config Document | A document where each field name is a private configuration field for the service and the value of each field is the name of a Secret that stores the configuration value. |
Service Rules¶
Rules for a specific external service are defined in the /<service
name>/rules
sub-directory.
Each rule maps to its own JSON file with the same name as the rule.
{ "id": "<Rule ID>", "name": "<Rule Name>", "actions": ["<Service Action Name>"], "when": <JSON Rule Expression> }
Field | Description |
---|---|
id String | A string that uniquely identifies the rule. Realm automatically generates a unique ID for a rule when you create it. |
name String | The name of the service rule. The name may be at most 64 characters long and can only contain ASCII letters, numbers, underscores, and hyphens. |
actions Array<String> | A list of service actions that the rule applies to. The specific
actions available depend on the service type . |
when Document | A rule expression that
evaluates to true when the rule applies to a given request. |
Incoming Webhooks¶
Incoming webhooks for a specific service are defined in the
/<service name>/incoming_webhooks/
sub-directory.
Incoming webhooks use the same configuration format as function but have additional configuration parameters.
Configuration¶
{ "id": "<Function ID>", "name": "<Function Name>", "private": <Boolean>, "can_evaluate": <Rule Expression>, "disable_arg_logs": <Boolean>, "run_as_system": <Boolean>, "run_as_user_id": "<Realm User ID>", "run_as_user_id_script_source": "<Function Source Code>", "respond_result": <Boolean>, "options": { "httpMethod": "<HTTP Method>", "validationMethod": "<Webhook Validation Method>", "secret": "<Webhook Secret>" } }
Field | Description | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id String | A value that uniquely identifies the function. Realm automatically generates a unique ID for a function when you create it. | |||||||||||||
name String | The name of the function. The name must be unique among all functions in your application. | |||||||||||||
private Boolean | If true , this function may only be accessed from incoming
webhooks, rules, and named functions. | |||||||||||||
can_evaluate Document | A rule expression that
evaluates to true when the function is allowed to execute in
response to a given request. | |||||||||||||
disable_arg_logs Boolean | If true , Realm omits the arguments provided to a function
from the function execution log entry. | |||||||||||||
run_as_system Boolean | If true , the webhook function runs as the system user. This overrides any values defined for
run_as_user_id and run_as_user_id_script_source . | |||||||||||||
run_as_user_id String | The unique ID of a Realm User that the
function always executes as. Cannot be used with
run_as_user_id_script_source . | |||||||||||||
run_as_user_id_script_source String | A stringified function that runs whenever the
webhook is called and returns the unique ID of a Realm
User that the function executes as. Cannot be used with
run_as_user_id . | |||||||||||||
respond_result Boolean | If true , Realm includes the webhook function return value as
the body of the HTTP response it sends to the client that
initiated the webhook request. | |||||||||||||
options Document | A document that contains configuration options for the webhook.
|
Source Code¶
exports = function() { // webhook function code };
Triggers¶
Triggers are defined in your application's
/triggers
directory.
Each trigger is defined in its own JSON file with the same name as the trigger.
yourRealmApp/ └── triggers/ └── <trigger name>.json
Configuration¶
{ "id": "<Trigger ID>", "name": "<Trigger Name>", "type": "<Trigger Type>", "function_name": "<Trigger Function Name>", "config": { "<Configuration Option>": <Configuration Value> }, "disabled": <Boolean>, }
Field | Description |
---|---|
id String | A string that uniquely identifies the Trigger. Realm automatically generates a unique ID for a trigger when you create it. |
name String | The name of the Trigger. The name may be at most 64 characters long and can only contain ASCII letters, numbers, underscores, and hyphens. |
type String | The type of application event that the trigger listens for. Valid Options:
|
function_name String | The name of the Realm Function that the Trigger
executes whenever it fires. The Trigger automatically passes
arguments to the function depending on the Trigger type . |
config Document | A document with fields that map to additional configuration
options for the trigger. The exact configuration fields depend on
the trigger |
disabled Boolean | If true , the trigger will not listen for any events and will
not fire. |
Hosting¶
Files that you want to host on Realm should be
included in your application's /hosting
directory. Each file will be
uploaded with the metadata defined in metadata.json
.
You can configure the metadata
for each hosted file in metadata.json
. This metadata configuration
file is an array of documents that each correspond to a single hosted
file's metadata attributes.
yourRealmApp/ └── hosting/ ├── metadata.json └── files/ └── <files to host>
Metadata Configuration¶
[ { "path": "<File Resource Path>", "attrs": [{ "name": "<Attribute Type>", "value": "<Attribute Value>" }] } ]
Field | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
path String | The resource path of the file. | ||||||||||
attrs Array<Document> | An array of documents where each document represents a single metadata attribute. Attribute documents have the following form: Metadata Attribute Document
|
If you do not specify a Content-Type
attribute for a file, MongoDB Realm
will attempt to automatically add a Content-Type
attribute to it
based on the file extension.
For example, Realm would automatically add the attribute
Content-Type: application/html
to the file myPage.html
.
Values¶
Values are defined in your application's /values
directory.
Each value is defined in its own JSON file named after the value.
yourRealmApp/ └── values/ └── <value name>.json
Configuration¶
{ "id": "<Value ID>", "name": "<Value Name>", "from_secret": <boolean>, "value": <Stored JSON Value|Secret Name> }
Field | Description |
---|---|
id String | A string that uniquely identifies the value. Realm automatically generates a unique ID for a value when you create it. |
name String | A unique name for the value. This name is how you refer to the value in functions and rules. |
from_secret Boolean | Default: false . If true , the value exposes a
Secret instead of a plain-text JSON value. |
value String, Array, or Object | The stored data that Realm exposes when the value is referenced. If If |