Configure environment variables for deployment

The .magento.env.yaml file uses environment variables to centralize the management of build and deploy actions across all of your environments, including Pro Staging and Production. To configure unique actions in each environment, you must modify this file in each environment.

File structure

The .magento.env.yaml file contains two sections: stage and log. The stage section controls actions that occur during the phases of the Cloud deployment process.

Environment variables

The ece-tools package sets values in the env.php file based on values from Cloud variables, variables set in the Cloud Console, and the .magento.env.yaml configuration file. The environment variables in the .magento.env.yaml file customize the Cloud environment by overriding your existing Commerce configuration. If a default value is Not Set, then the ece-tools package takes NO action and uses the Commerce default or the value from the MAGENTO_CLOUD_RELATIONSHIPS configuration. If the default value is set, then the ece-tools package acts to set that default.

The following topics contain detailed definitions, such as whether a default value is set or not set, of all variables that you can use in the .magento.env.yaml file:

Create configuration file from CLI

You can generate a .magento.env.yaml configuration file for a Cloud environment using the following ece-tools commands.

Creates a configuration file

php ./vendor/bin/ece-tools cloud:config:create `<configuration-json>`

Update values in the configuration file

php ./vendor/bin/ece-tools cloud:config:update `<configuration-json>`

Both commands require a single argument: a JSON-formatted array that specifies a value for at least one build, deploy, or post-deploy variable. For example, the following command sets values for the SCD_THREADS and CLEAN_STATIC_FILES variables:

php vendor/bin/ece-tools cloud:config:create '{"stage":{"build":{"SCD_THREADS":5}, "deploy":{"CLEAN_STATIC_FILES":false}}}'

And creates a .magento.env.yaml file with the following settings:

stage:
  build:
    SCD_THREADS: 5
  deploy:
    CLEAN_STATIC_FILES: false

You can use the cloud:config:update command to update the new file. For example, the following command changes the SCD_THREADS value and adds the SCD_COMPRESSION_TIMEOUT configuration:

php vendor/bin/ece-tools cloud:config:update '{"stage":{"build":{"SCD_THREADS":3, "SCD_COMPRESSION_TIMEOUT":1000}}}'

The updated file contains the following configuration:

stage:
  build:
    SCD_THREADS: 3
    SCD_COMPRESSION_TIMEOUT: 1000
  deploy:
    CLEAN_STATIC_FILES: false

Validate configuration file

Use the following ece-tools command to validate the .magento.env.yaml configuration file before pushing changes to the remote Cloud environment.

php ./vendor/bin/ece-tools cloud:config:validate

The following sample response provides a list of items to correct:

Environment configuration is not valid. Correct the following items in your .magento.env.yaml file:
The SCD_THREADS variable contains an invalid value of type string. Use the following type: integer.
The SCD_STRATEGY variable contains an invalid value fast. Use one of the available value options: compact, quick, standard.
The NOT_EXIST_OPTION variable is not allowed in configuration.

PHP constants

You can use PHP constants in .magento.env.yaml file definitions instead of hard-coding values. The following example defines the driver_options using a PHP constant:

stage:
  deploy:
    DATABASE_CONFIGURATION:
      connection:
        default:
          driver_options:
            !php/const:\PDO::MYSQL_ATTR_LOCAL_INFILE : 1
        indexer:
          driver_options:
            !php/const:\PDO::MYSQL_ATTR_LOCAL_INFILE : 1
      _merge: true

Error handling

When a failure occurs because of an unexpected value in the .magento.env.yaml configuration file, you receive an error message. For example, the following error message presents a list of suggested changes to each item with an unexpected value, sometimes providing valid options:

- Environment configuration is not valid. Please correct .magento.env.yaml file with next suggestions:
  Item CRON_CONSUMERS_RUNNER is not supposed to be in stage build. Please move it to one of possible stages: global, deploy
  Item SKIP_SCD has unexpected type string. Please use one of next types: boolean
  Item VERBOSE_COMMANDS has unexpected type boolean. Please use one of next types: string
  Item SKIP_HTML_MINIFICATION has unexpected type string. Please use one of next types: boolean
  Item CRON_CONSUMERS_RUNNER has unexpected type boolean. Please use one of next types: array
  Item VAR_WARM_UP_PAGES is not allowed in configuration.
  Item WARM_UP_PAGES has unexpected type string. Please use one of next types: array

Make any corrections, commit, and push the changes. If you do not receive an error message, then the changes to your configuration file pass the validation.

Configuration management optimization

If you have enabled Configuration Management after dumping the configurations, you should move the SCD_* variables from the deploy to the build stage. See Static content deployment strategies.

Before Configuration Management:

  deploy:
    CRON_CONSUMERS_RUNNER:
      cron_run: true
      consumers: []
    SCD_STRATEGY: compact
    SCD_MATRIX:
      ...
    REDIS_USE_SLAVE_CONNECTION: 1

After enabling Configuration Management, move the SCD_* variables to the build stage:

  deploy:
    CRON_CONSUMERS_RUNNER:
      cron_run: true
      consumers: []
    REDIS_USE_SLAVE_CONNECTION: 1
  build:
    SCD_STRATEGY: compact
    SCD_MATRIX:
      ...