Configuring the Commerce Engine using environment variables

Abstract

How to use environment variables to configure the Commerce Engine.

You can use a variables file to configure Commerce Engine environments. The Commerce Engine uses placeholders in configuration and environment files, instead of actual values. The configuration values are defined as variables in an environment variables file. The use of environment variables lets you configure all your XC environments together. You can use the same environment variables file to define multiple sets of environment variables for distinct instances of the Commerce Engine, for example, for development and production environments.

Notation of placeholders in Commerce Engine configuration files

In Commerce Engine configuration files, environment parameters are prefixed with the string PlaceholderFor. These environment configuration parameters do not need to have specific values defined in configuration files, but instead can take their values from environment variables. The following example shows some environment parameters in the global.json configuration file that contain the PlaceholderFor segment as part of their value, and that you can replace using environment variables.

{
 "$type": "Sitecore.Commerce.Plugin.Management.SitecoreConnectionPolicy, Sitecore.Commerce.Plugin.Management",
 "Host": "PlaceholderForSitecoreHost",
 "SitecoreDatabase": "PlaceholderForSitecoreDatabase",
 "UserName": "PlaceholderForSitecoreUsername",
 "Domain": "PlaceholderForSitecoreDomain",
 "Password": "PlaceholderForSitecorePassword",
 "ConnectionLeaseTimeout": "PlaceholderForConnectionLeaseTimeout|int",
 "AuthRequestUrl": "sitecore/api/ssc/auth/login",
 "Protocol": "PlaceholderForSitecoreProtocol",
 "AllowAnonymousUser": "PlaceholderForSitecoreAllowAnonymousUser|bool"
}

The string that represents a placeholder in the configuration file can only contain the following characters:

  • Lowercase letters (a-z)

  • Uppercase letters (A-Z)

  • Hyphen ("-")

  • Underscore ("_")

    Note

    Placeholder notations cannot contain numbers.

At runtime, when XC loads configuration from the various files, it looks up the environment variables file and, for each matching parameter, uses the corresponding environment variable. The following is an example of environment variables from the launchSettings.json file, in Visual Studio, defining parameter values that could replace the placeholders used in the previous example.

{
 "$type": "Sitecore.Commerce.Plugin.Management.SitecoreConnectionPolicy, Sitecore.Commerce.Plugin.Management",
 "COMMERCEENGINE_SitecoreHost": "sxa.storefront.com",
 "COMMERCEENGINE_SitecoreDatabase": "master",
 "COMMERCEENGINE_SitecoreUsername": "admin",
 "COMMERCEENGINE_SitecoreDomain": "sitecore",
 "COMMERCEENGINE_SitecorePassword": "b",
 "COMMERCEENGINE_SitecoreProtocol": "http",
 "COMMERCEENGINE_SitecoreAllowAnonymousUser": "false",
}

Supported data types in placeholders

When Sitecore XC constructs the parameter value from an environment variable, it assumes that the data type is a string, unless otherwise specified. Other supported data types are integer and boolean. In configuration files, data types (other than string) are appended at the end of the value, and separated by a pipe (|), as shown in the following example:

Type

Placeholder value in configuration files

string

"PlaceholderForSitecoreHost"

Note

String type is implicit.

boolean

"PlaceholderForSitecoreAllowAnonymousUser|bool"

integer

"PlaceholderForIntegerValue|int"

Environment variables in launchSettings.json

When starting the Commerce Engine from Visual Studio, environment variables are loaded from the launchSettings.json file located in the Properties folder of the reference Sitecore.Commerce.Engine project (in the Sitecore.Commerce.Engine.SDK). The sample launchSettings.json file predefines environment variable profiles for a "Development" environment, and for a "Production" environment, as shown in the following example:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "https://localhost:5000/",
      "sslPort": 0
    }
  },
  "profiles": {
    "IISExpress": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "launchUrl": "api/$metadata",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "COMMERCEENGINE_AppSettings__DeploymentId": "HabitatAuthoring01",
        "COMMERCEENGINE_AppSettings__EnvironmentName": "HabitatAuthoring",
  ...
      }
    },
    "Engine": {
      "commandName": "Project",
      "launchUrl": "https://localhost:5000/api/$metadata",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "COMMERCEENGINE_AppSettings__DeploymentId": "HabitatAuthoring01",
 ...
      }
    },
    "EngineProduction": {
      "commandName": "Project",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production",
        "COMMERCEENGINE_AppSettings__DeploymentId": "HabitatAuthoring01",
        "COMMERCEENGINE_AppSettings__EnvironmentName": "HabitatAuthoring",
 ...
      }
    }
  }
} 

Note

The example does not show all predefined variables. For a complete list of predefined environment variables, refer to the sample launchSettings.json file in the Sitecore.Commerce.SDK.

Environment variables in docker-compose.yml

When running a containerized XC solution, environment variables defined in the ./docker-compose.yml file are loaded. The ./docker-compose.yml file predefines environment variables, as shown in the following sample:

engine_authoring:
  image: ${XC_SITECORE_DOCKER_REGISTRY}sitecore-xc1-engine:${XC_PACKAGES_TAG}
  depends_on:
      mssql:
        condition: service_healthy
      solr:
        condition: service_started
      id:
        condition: service_started
      redis:
        condition: service_started
    environment:
      COMMERCEENGINE_AppSettings__DeploymentId: HabitatAuthoring01
      COMMERCEENGINE_AppSettings__EnvironmentName: HabitatAuthoring
      COMMERCEENGINE_AppSettings__SitecoreIdentityServerUrl: http://${IDENTITY_SERVICE_IP}
      COMMERCEENGINE_AppSettings__AllowedOrigins: http://${XC_BIZFX_IP}|http://${CM_SERVICE_IP}|http://${CD_SERVICE_IP}
      COMMERCEENGINE_AppSettings__AntiForgeryEnabled: "false"
      COMMERCEENGINE_AppSettings__UseHttpsInKestrel: "false"
      COMMERCEENGINE_Caching__Redis__Options__Configuration: ${REDIS_SERVICE_IP}
      COMMERCEENGINE_Caching__Redis__Options__InstanceName: Redis
      COMMERCEENGINE_CommerceConnector__ClientId: ${XC_ENGINE_CONNECT_CLIENTID}
      COMMERCEENGINE_GlobalDatabaseName: ${XC_GLOBAL_DB}
      COMMERCEENGINE_GlobalDatabaseServer: ${SITECORE_MSSQL_SERVICE_IP}
      COMMERCEENGINE_GlobalDatabaseUserName: sa
      COMMERCEENGINE_GlobalDatabasePassword: ${SQL_SA_PASSWORD}
      COMMERCEENGINE_GlobalTrustedConnection: "${XC_GLOBAL_DB_TRUSTED_CONNECTION}"
      COMMERCEENGINE_SharedDatabaseName: ${XC_SHARED_DB}
      COMMERCEENGINE_SharedDatabaseServer: ${SITECORE_MSSQL_SERVICE_IP}
      COMMERCEENGINE_SharedDatabaseUserName: sa
      COMMERCEENGINE_SharedDatabasePassword: ${SQL_SA_PASSWORD}
      COMMERCEENGINE_SharedTrustedConnection: "${XC_SHARED_DB_TRUSTED_CONNECTION}"

Note

The example does not show all predefined variables. For a complete list of predefined environment variables, refer to the sample ./docker-compose.yml file.