Magento application environment variables

These sections list the environment variables for general Magento, build, and deployment. You can add variables using the Project Web Interface or CLI commands.

Magento application variables

The following table lists variables that you can override using environment variables.

Variable name Description Default value
ADMIN_USERNAME User name for a Magento administrative user. This user is an administrator and can create other users, including other administrative users. admin
ADMIN_FIRSTNAME Administrative user's first name. John
ADMIN_LASTNAME Administrative user's last name. Doe
ADMIN_EMAIL Administrative user's e-mail address. This value is required for upgrading and patching Magento Commerce (Cloud) and is used to send password reset emails. To set, see Add admin variables for Admin access. Not set
ADMIN_PASSWORD Administrative user's password. Initially, we generate a random password and provide an email directing the Project Owner to reset the password. You should immediately change this password. Not set
ADMIN_URL Enter the relative URL by which to access the Magento Admin. For security reasons, we recommend you choose a value other than admin or backend or another term that is easy to guess. admin
ADMIN_LOCALE Specifies the default locale used by the Magento Admin. en_US
APPLICATION_MODE

Determines whether or not Magento operates in developer mode or in production mode. During deployment, we recommend the default mode.

The variable supports the following values: production and developer. You cannot set this value to default mode. After you have changed the mode with an environment variable, it can only be set to production or developer.

To execute build and deploy scripts in a specific mode, set an environment variable for APPLICATION_MODE. If you execute these scripts in default mode without APPLICATION_MODE set as an environment variable, the mode will be set to production.

production
CLEAN_STATIC_FILES

The default value, enable, cleans generated static view files when you perform an action like enabling or disabling a component. We recommend the default value in development. The supported values are enable and disable.

Failure to clear static view files might result in issues if there are multiple files with the same name and you don't clear all of them.

Because of static file fallback rules, if you do not clear static files and there is more than one file named logo.gif that are different, fallback might cause the wrong file to display.

enable
UPDATE_URLS

On deployment, replace Magento base URLs in the database with project URLs. This is useful for local development, where base URLs are set up for your local environment. When you deploy to a Cloud environment, we change the URLs so you can access your storefront and Magento Admin using project URLs.

You should set this variable to disabled only in Staging or Production, where the base URLs can't change.

Available in Magento Commerce (Cloud) 2.0.10 and later, and 2.1.2 and later.

enabled

For additional build and deploy variables, continue to the following sections.

Magento build variables

The following variables are options available during the build process of build and deploy. The variables help prepare the codebase before it is moved to the server and then built.

You can use these options as part of a build_options.ini file for customizing the build process. This file is located in the Magento root directory.

Variable name Description Default value
BUILD_OPT_SKIP_DI_COMPILATION If you are needing to quickly debug a set of code in developer mode, you can enable this option to skip compilation and before a build immediately. Compilation can take additional time to properly manage, compile, and then build your code. We only recommend this option for quick debug testing in developer mode. You should always run di_compilation. Available in versions 2.1.2 and later, 2.2.X. For 2.2.X, we have removed `skip_di_compilation` from `build-options.ini` as it cannot be skipped during the build phase. skip_di_compilation = disabled
BUILD_OPT_SKIP_DI_CLEARING Before di_generation runs, the build process clears the existing build to rebuild before deploying. If you are simply redeploying without needing to fully rebuild, you can use this option to skip the deletion of the existing built files. The deploy phase will reuse the existing build files. Available in versions 2.1.2 and later, 2.2.X. For 2.2.X, we have removed `skip_di_clearing` from `build-options.ini` as it cannot be skipped during the build phase. skip_di_clearing = disabled
BUILD_OPT_SCD_EXCLUDE_THEMES When enabled, this option does not generate static content for an entered theme location. This is extremely helpful when static content deployment occurs during the build phase. For example, the Luma theme is included with all Magento Commerce (Cloud) projects. To exclude this theme, you would enter exclude_themes = Magento/luma. You may not need to constantly generate static content for this theme, which adds time to your build. Available in versions 2.1.4 and later, 2.2.X. exclude_themes =
BUILD_OPT_SCD_THREADS

Sets the number of threads for processing and deploying static content files. These threads are used The higher amount of threads increasing the amount of files processed during the deployment of static content during the build phase. The lower the number of threads, the slower static files are processed increasing deployment time.

For Starter plan environments and Pro Integration environments, the threads value is 1. This amount is fine for these environments. For Pro Staging and Production environments, the default threads is 3 to increase the speed of processing static content, especially for Production with three nodes and GlusterFS.

To further reduce deployment time, we recommend using Configuration Management with the scd-dump command to move static deployment into the build phase.

Available in versions 2.1.4 and later, 2.2.X.

scd_threads = 1 for all Starter environments and Pro Integration environments
scd_threads = 3 for Pro Staging and Production environments
BUILD_OPT_SKIP_SCD Skips static content deployment during the build phase. If you are already deploying static content during the build phase with Configuration Management, you may want to turn it off for a quick build test. We do not recommend using this option as running static deployment during the deployment phase can greatly increase deployment times and downtime for your live site. Available in versions 2.1.4 and later, 2.2.X. skip_scd = disabled
GENERATED_CODE_SYMLINK

This variable enables the var/generation and var/di generated folders to be writable. Available in versions 2.1.X.

This variable was removed in 2.2. In 2.2 var/generation and var/di content is moved to generated/. This folder is removed after build and deploy completes.</p>
GENERATED_CODE_SYMLINK = disabled

For information on the build and deploy process, see Deployment process.

Magento deploy variables

The following variables are available during the deploy process of build and deploy. To know what version the variable is available on, see the Magento Version in the table.

Variable name Description Default value
UPDATE_URLS

On deployment, replace Magento base URLs in the database with project URLs. This is useful for local development, where base URLs are set up for your local environment. When you deploy to a Cloud environment, we change the URLs so you can access your storefront and Magento Admin using project URLs.

You should set this variable to disabled only in Staging or Production environments, where the base URLs can't change. For Pro, we already set this to disabled for you.

This is available in versions 2.0.10 and later, 2.1.2 and later, and 2.2 and later.

enabled
CLEAN_STATIC_FILES

The default value, enable, cleans generated static view files when you perform an action like enabling or disabling a component. We recommend the default value in development. The supported values are enable and disable.

Failure to clear static view files might result in issues if there are multiple files with the same name and you don't clear all of them.

Because of static file fallback rules, if you do not clear static files and there is more than one file named logo.gif that are different, fallback might cause the wrong file to display.

This is available in all versions.

enabled
STATIC_CONTENT_EXCLUDE_THEMES Themes can include numerous files. If you want to skip copying over theme files during deployment, you can set this environment variable. For example, the Luma theme is included with Magento Commerce (Cloud). You may not need to constantly deploy this theme with your code updates and deployments. To exclude, you would add the theme, for example: Magento/luma. This is available in all versions. not set
ADMIN_LOCALE Specifies the default locale used by the Magento Admin. This is available in all versions. en_US
STATIC_CONTENT_THREADS

Sets the number of threads for processing and deploying static content files. The higher amount of threads increasing the amount of files processed during the deployment. The lower the number of threads, the slower static files are processed increasing deployment time.

For Starter plan environments and Pro Integration environments, the threads value is 1. This amount is fine for these environments. For Pro Staging and Production environments, the default threads is 3 to increase the speed of processing static content, especially for Production with three nodes and GlusterFS.

To further reduce deployment time, we recommend using Configuration Management with the scd-dump command to move static deployment into the build phase.

This is available in all versions.

1 for Starter environments and Pro Integration environments
3 for Pro Staging and Production environments
DO_DEPLOY_STATIC_CONTENT You can forcefully enable or disable the deployment of static content during the deploy phase with this variable. If you already completed static content deployment in the build phase, and this variable is enabled, it will be overridden to ensure static content deployment occurs only once. We strongly recommend always deploying static content during the build phase. This is available in all versions. disabled
MAGENTO_CLOUD_MODE We manage the values and setting of this variable. It identifies the type of environment as part of Integration, Staging, or Production. For example, for Pro, this value may be enterprise indicating Staging and Production. For enterprise, it sets the STATIC_CONTENT_THREADS to 3, otherwise sets it to 1 for Integration. This is highly important for Pro plans Production, which has a three node high availability architecture with a very different technology stack. This is available in all versions. enterprise
APPLICATION_MODE

Determines whether or not Magento operates in developer mode or in production mode. During deployment, we recommend the default mode.

The variable supports the following values: production and developer. You cannot set this value to default mode. After you have changed the mode with an environment variable, it can only be set to production or developer.

To execute build and deploy scripts in a specific mode, set an environment variable for APPLICATION_MODE. If you execute these scripts in default mode without APPLICATION_MODE set as an environment variable, the mode will be set to production.

This is available in all versions.

production
VERBOSE_COMMANDS Enables or disables the Symfony debug verbosity level for your logs. Be aware, if you enable this verbosity, the logs will be deeply detailed. This is available in all versions. disabled
ADMIN_USERNAME User name for a Magento administrative user. This user is an administrator and can create other users, including other administrative users. This is available in all versions. admin
ADMIN_FIRSTNAME Administrative user's first name. This is available in all versions. Not set, example: John
ADMIN_LASTNAME Administrative user's last name. This is available in all versions. Not set, example: Doe
ADMIN_EMAIL Administrative user's e-mail address. This value is required for upgrading and patching Magento Commerce (Cloud) and is used to send password reset emails. To set, see Add admin variables for Admin access. Not set
ADMIN_PASSWORD Administrative user's password. Initially, we generate a random password and provide an email directing the Project Owner to reset the password. You should immediately change this password. Not set
ADMIN_URL Enter the relative URL by which to access the Magento Admin. For security reasons, we recommend you choose a value other than admin or backend or another term that is easy to guess. If you set this value through a variable and the Admin Panel in Starter environments, the variable overrides the Admin Panel (or database value). For Pro, the Admin Panel (database value) overrides the variable. The values are also managed by UPDATE_URLS. This is available in all versions. admin
STATIC_CONTENT_SYMLINK Generates symlinks for static content. By default, symlinks are always generated unless you disable it using this environment variable. This setting is vital for Pro Production environment for the three node cluster. If disabled, every file will be copied during deployment without automated symlinks generated. If disabled, this will increase deployment time. This is available in all versions. enabled

For information on the build and deploy process, see Deployment process.

Add environment variables

You can add environment variables for active environments through the Project Web Interface and through the Magento Cloud CLI. To create variables through the Project Web Interface, see Set environment variables.

Everytime you add or modify a variable using the web interface or the CLI, the branch will redeploy automatically.

To create a variable using the command line:

  1. Login to the Magento Cloud CLI. Enter the command magento-cloud login and provide your credentials.
  2. To set a variable for the project, use the command magento-cloud project:variable:set <name> <value>. The alias for this command is also pvset. For example, magento-cloud pvset example 123 creates a variable example with a string value of 123 for the project.
  3. After creating these variables, you can list all project variables with the command magento-cloud project:variable:get or magento-cloud pvget.
  4. To set a variable for the branch, use the command magento-cloud variable:set <name> <value>. The alias for this command is also vset. For example, magento-cloud vset example2 abc creates a variable example2 with a string value of abc for the branch.
  5. After creating these variables, you can list all project variables with the command magento-cloud variable:get or magento-cloud vget.

Troubleshooting

In the event something goes wrong and you can’t access your environment after it deploys, try the following:

  • SSH to the environment and make sure services are running.
  • Restore your snapshot:

    magento-cloud snapshot:list
    magento-cloud snapshot:restore <snapshot>
    

For more information on snapshots, see Snapshots and backup management.