Configuring the Commerce Engine using environment variables
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 ("_")
NotePlaceholder 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 |
Note String type is implicit. |
boolean |
|
integer |
|
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",
...
}
}
}
}
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. For example:
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}"
The example does not show all predefined variables. For a complete list of predefined environment variables, refer to the sample ./docker-compose.yml
file.