In this article, we will review how environment variables are utilised in the Commerce Engine solution. These are findings that provide some more context on top of Commerce Developer Reference: Configuring the Commerce Engine using environment variables, which will allow us to work with them more effectively.
Introduction
Environment variables are primarily utilised in 3 areas of the Commerce Engine and each area has nuances that we need to be aware of. The first area is in the Commerce Engine configuration file, config.json. The second is the global environment configuration, global.json. The third are is made up of the role environment and policy set configurations.
Environment variables will only be consumed into the Commerce Engine’s configuration builder if they are prefixed with "COMMERCEENGINE_".
Environment Variable Usage in Configuration Files
The Commerce Engine Configuration File (config.json)
Using the environment variable configuration provider, the config.json is updated without the need for placeholders or data type specification.
Updating a property value simply requires adding an environment variable that represents the path of the property to be overridden.
For example, adding the environment variable, COMMERCEENGINE_Serilog__MinimumLevel__Default: Information, will override the corresponding configuration property by resolving it to the structure of the configuration.
{
"AppSettings": { ... },
"Serilog": {
...
"MinimumLevel": {
"Default": "Warning",
...
}
},
...
}
While the placeholder values aren’t relevant to the overrides themselves, the Commerce Engine is distributed with ‘PlaceholderFor<property>’ values in config.json. Consider these flags to ensure that environment variables are not omitted. When replacing other properties in the Commerce Engine configuration, placeholders are not required.
The Global Environment Configuration File (global.json)
Similar to the config.json, the global environment configuration file, global.json, is loaded during the start up process of the Commerce Engine. However, while the Commerce Engine leverages the environment variables for this configuration, the replacement strategy differs from the environment variable configuration provider in that instead of resolving variables to the structure of the configuration file it instead resolves via placedholder matches.
For example, the environment variable COMMERCEENGINE_GlobalDatabaseUserName: sa will override the corresponding configuration property by resolving it to the placeholder.
{
...
"Name": "GlobalEnvironment",
"Policies: {
"$type": "System.Collections.ObjectModel.ReadOnlyCollection`1[[Sitecore.Commerce.Core.Policy, Sitecore.Commerce.Core]], mscorlib",
"$values": [
...
{
"$type": "Sitecore.Commerce.Plugin.SQL.EntityStoreSqlPolicy, Sitecore.Commerce.Plugin.SQL",
...
"UserName": "PlaceholderForGlobalDatabaseUserName",
...
},
...
]
}
}
Role Environment and Policy Set Configuration Files
For environment variables used in role environment and policy set configurations, the Commerce Engine also uses the same strategy as per the global.json (placeholder matching over structure resolution), however the replacement is performed at the time of bootstrapping the Commerce Engine, not during the start up process of the Commerce Engine.
This means that while the role environment and policy set configurations will retain the ‘PlaceholderFor…’ values on disk, the engine startup will still load configurations from the commerce global database. Therefore, the Commerce Engine role will not resolve changes during the start up process with updated variables (e.g. running docker-compose up for containers).
Changing environment variables used in role environment and policy set configuration files, should be thought the same as making changes to the configuration files themselves, where bootstrapping the Commerce Engine is required to consume the changes.
Supported Data Types in Placeholders
In Commerce Developer Reference: Configuring the Commerce Engine using environment variables, it 3 mentions supported data types for placeholders, where string is the implicit (default) type, and boolean and integer values can be represented by appending ‘|bool’ and ‘|int’ to placeholder names respectively.
The reality is that under the hood all that is happening is identifying whether the value should be wrapped with quotation marks or not. This means that we can actually support other data types, such as decimals by appending either ‘|bool’ or ‘|int’ to the placeholder.
Data types apply to placeholders in the global environment, role environment and policy set configuration files. They do not apply to placeholders in the Commerce Engine configuration file (config.json).
| Placeholder | Values | Results |
| “PlaceholderForMyVariable” | dev.sitecore.com true | “dev.sitecore.com” “true” |
| “PlaceholderForMyVariable|bool” or “PlaceholderForMyVariable|int” | dev.sitecore.com true 3 1.2 (decimal) | dev.sitecore.com true 3 1.2 |
Summary
The following table summarises how environment variables are utilised in the various configuration files of the Commerce Engine.
| Configuration File(s) | Property Resolver | Allows Fallback / Default Value* | Applies | Applied By | Requires Bootstrap |
| config.json | Structure | Yes | During start up | Environment variable configuration provider (.Net Core) | No |
| global.json | Placeholder | No | During start up | Commerce Engine | No |
| Environment/Policy Set Configurations | Placeholder | No | During Bootstrap | Commerce Engine | Yes |