Magento application environment variables

This topic describes Magento application and deploy environment variables as well as build options.

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

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

Magento build options

The following options are available during the build phase. These options help prepare the codebase before it is moved to the server and built.

To use these options, create a build_options.ini file in your root Magento project directory and push it to your environment.

Example build_options.ini file

;exactly
VERBOSE_COMMANDS=enabled

; A path to a Magento theme. Don't generate static content for the specified theme. Adds the --exlude-theme option to the php ./bin/magento setup:static-content:deploy command.
exclude_themes=magento/luma

; A number (0-9) that specifies which gzip compression level to use when compressing static content; 0 disables compression.
;SCD_COMPRESSION_LEVEL=0

; A number, defaults to 0, that specifies how many threads to use for static content deployment. Increases and descreases processing speed. Passed into --max-procs xargs flag.
scd_threads=2

; A string that gets passed to the -s flag of the php ./bin/magento setup:static-content:deploy command. No validation.
scd_strategy=standard

; Skips static content deployment during the build phase.
skip_scd=yes
Option Description Default value
exclude_themes

When enabled, this option does not generate static content for the specified theme location. This is helpful when static content deployment occurs during the build phase.

For example, the Luma theme is included with all Magento Commerce (Cloud) projects. You may not need to constantly generate static content for this theme, which adds time to your build. To exclude the theme, use the following: exclude_themes=magento/luma.

Not set
SCD_COMPRESSION_LEVEL Specifies which gzip compression level (0 - 9) to use when compressing static content; 0 disables compression. 6
scd_strategy

Allows you to customize the deployment strategy for static content. refer to Deploy static view files for more information.

Use these options only if you have more than one locale.

  • standard: deploys all static view files for all packages.
  • quick: minimizes deployment time. This is the default command option if not specified.
  • compact: conserves disk space on the server. If you use compact, it overrides the value for scd_threads with a value of 1. This strategy does not work with multi-threads.
standard
scd_threads

Sets the number of threads for static content deployment. Increasing the number of threads speeds up static content deployment; decreasing the number of threads slows it down.

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

scd_threads=1 - Starter environments and Pro Integration environments

scd_threads=3 - Pro Staging and Production environments

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 because running static content deployment during the deployment phase can greatly increase deployment times and downtime for your live site. Available in 2.2.X.

Not set

The following variables were removed in v2.2:

  • skip_di_clearing
  • skip_di_compilation

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

Magento deploy variables

The following variables are available during the deploy process.

You can add variables using the Project Web Interface or CLI commands.

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 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
SCD_COMPRESSION_LEVEL Specifies which gzip compression level (0 - 9) to use when compressing static content; 0 disables compression. 6
SCD_STRATEGY

The variable allows you to customize the deployment strategy for static content deployment. The deploy script includes the -s flag with a default setting of `quick` for the static content deployment strategy. For details on these options and features, see Static files deployment strategies and the -s flag for Deploy static view files. This is available for 2.2.X.

Use these options only if you have more than one locale.

  • standard: deploys all static view files for all packages.
  • quick: minimizes deployment time. This is the default command option if not specified.
  • compact: conserves disk space on the server. If you use compact, the value for STATIC_CONTENT_THREADS is overriden with a value of 1. This strategy does not work with multi-threads.
not set

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.