Docs Menu

Docs HomeAtlas App Services

Create Template Configurations with Expansions

On this page

  • Define a Template
  • Define Environment Values
  • Define an Expansion Replacement
  • Specify an Environment
  • Create a New Templated App
  • Development Workflow

Atlas App Services supports a replacement operator (%()) that dynamically resolves JSON expansions like %%environment in your configuration files. When you create a new app with configuration files that include expansions (either with Realm CLI or through GitHub), App Services automatically resolves the expansions and uses the resolved configuration files to create the app.

Important

Configuration files that use the replacement operator are templates. App Services does not resolve the expansions after it creates the app. Instead, it uses a copy of the configuration files that reflect the resolved values at the time the app was created.

1

You can use expansions to template any environment. For each environment that you use, define values that you reference in your configuration files.

Example

The following environments configure different MongoDB Atlas cluster names:

environments/development.json
{
"values": {
"clusterName": "atlas-development"
}
}
environments/production.json
{
"values": {
"clusterName": "atlas-production"
}
}
2

You can reference any environment value from a configuration file with the %() replacement operator and the %%environment expansion. Define expansions for each configuration file you want to template.

Example

The following template configuration file for the mongodb-atlas data source uses expansions to dynamically resolve clusterName based on the environment:

data_sources/mongodb-atlas/config.json
{
"name": "mongodb-atlas",
"type": "mongodb-atlas",
"config": {
"clusterName": "%(%%environment.values.clusterName)",
"readPreference": "primaryPreferred",
"wireProtocolEnabled": true
}
}
3

Choose which environment to deploy your app to and then update the app configuration with the environment name:

realm_config.json
{
"name": "MyApp",
"environment": "development",
"deployment_model": "LOCAL",
"location": "aws-us-east-1"
}

Tip

If you do not specify an environment, %%environment expansions resolve to values in environments/no-environment.json.

4

You can now use your templated configuration files to create a new app in your chosen environment.

Example

App Services uses the template configuration to generate new, resolved configuration files on import:

realm-cli push
data_sources/mongodb-atlas/config.json
{
"name": "mongodb-atlas",
"type": "mongodb-atlas",
"config": {
"clusterName": "atlas-development",
"readPreference": "primaryPreferred",
"wireProtocolEnabled": true
}
}

You can use configuration expansions for any App, but the most useful case is for teams that develop a production application with source code files stored in an external version control system like GitHub. You can create independent apps to develop features or test changes and use expansions to customize the apps based on their environment.

  1. Create a new app from the common template with the environment set to development. If you're using Git, create a new branch on GitHub and check out a local copy.

  2. Make changes and test them locally against the development app. Any changes you make to the app won't affect the production app, though they may still read and write production data sources and services unless you configure alternatives.

  3. Commit changes and merge them back to production. You can set up a CI/CD pipeline, which may itself create an app in the test environment, to validate and merge your changes into the production branch.

  4. Once your changes are merged, you can safely delete the development app and clean up any other associated services.

←  Third-Party Service Configuration FilesApplication Configuration Files (Legacy) →
Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.