---
title: "Configuring the Commerce Engine using environment variables"
slug: "configuring-the-commerce-engine-using-environment-variables"
abstract: "How to use environment variables to configure the Commerce Engine."
---
# 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.

```csharp
{
 "$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.

```csharp
{
 "$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"`<br><br>> [!note]<br>> 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](https://doc.sitecore.com/xp/en/developers/101/sitecore-experience-commerce/sitecore-commerce-engine-sdk.html "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:

```csharp
{
  "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](https://doc.sitecore.com/xp/en/developers/101/sitecore-experience-commerce/sitecore-commerce-engine-sdk.html "Sitecore Commerce Engine 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}"

```

> [!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.