Deploy variables

The following deploy variables control actions in the deploy phase and can inherit and override values from the Global variables. Insert these variables in the deploy stage of the .magento.env.yaml file:

stage:
  deploy:
    DEPLOY_VARIABLE_NAME: value

For more information about customizing the build and deploy process:

CACHE_CONFIGURATION

Use CACHE_CONFIGURATION to merge or override cache frontend and backend options generated during deployment.

For Adobe Commerce on cloud infrastructure, do not edit app/etc/env.php directly. The ece-tools package generates the deployment configuration from .magento.env.yaml, service relationships, and supported deployment variables.

Use VALKEY_BACKEND or REDIS_BACKEND to select the supported cache or L2 implementation for the exact Adobe Commerce release. Use CACHE_CONFIGURATION to customize options like connection retries, read timeouts, cache prefixes, or preload keys.

The supported backend and cache-service combination depends on the Commerce release and patch level. Redis is not supported for Adobe Commerce 2.4.9 or for patch releases later than 2.4.5-p16, 2.4.6-p14, 2.4.7-p9, and 2.4.8-p4. Use Valkey for releases where the system requirements require it.

By default, the deployment process overwrites the corresponding cache configuration. To merge the specified values with the generated configuration, set _merge to true:

stage:
  deploy:
    CACHE_CONFIGURATION:
      _merge: true
      frontend:
        default:
          backend_options:
            connect_retries: 3
          remote_backend_options:
            read_timeout: 10

To replace the existing configuration with the values specified in CACHE_CONFIGURATION, set _merge to false.

The following example merges database assignments into an existing cache configuration. Use this type of override only when the selected backend and Commerce release support it. Apply frontend settings to symfony_l2 only if the current Symfony L2 documentation explicitly supports the option.

stage:
  deploy:
    CACHE_CONFIGURATION:
      _merge: true
      frontend:
        default:
          backend_options:
            database: 10
        page_cache:
          backend_options:
            database: 11

The following example uses the Redis preload feature as defined in the Configuration guide. Use the corresponding Valkey guidance for releases that use Valkey.

stage:
  deploy:
    CACHE_CONFIGURATION:
      _merge: true
      frontend:
        default:
          id_prefix: '061_'
          backend_options:
            preload_keys:
              - '061_EAV_ENTITY_TYPES:hash'
              - '061_GLOBAL_PLUGIN_LIST:hash'
              - '061_DB_IS_UP_TO_DATE:hash'
              - '061_SYSTEM_DEFAULT:hash'

To use a custom REDIS_BACKEND model that is not in the allowed list, set _custom_redis_backend to true so that ece-tools applies the appropriate validation:

stage:
  deploy:
    CACHE_CONFIGURATION:
      frontend:
        default:
          _custom_redis_backend: true
          backend: '\CustomRedisModel'

CLEAN_STATIC_FILES

Enables or disables cleaning static content files generated during the build or deploy phase. Use the default value true in development as a best practice.

If you modify static content through a separate process, set the value to false.

stage:
  deploy:
    CLEAN_STATIC_FILES: false

Failure to clean static view files before deploying can cause problems if you deploy updates to existing files without removing the previous versions. Because of static file fallback rules, fallback operations can display the wrong file if the directory contains multiple versions of the same file.

CRON_CONSUMERS_RUNNER

Use this environment variable to confirm that message queues are running after a deployment.

The following example runs selected consumers and starts multiple processes for each one:

stage:
  deploy:
    CRON_CONSUMERS_RUNNER:
      cron_run: true
      max_messages: 1000
      consumers:
       example_consumer_1
       example_consumer_2
      multiple_processes:
        example_consumer_1: 4
        example_consumer_2: 3

The following example runs all consumers:

stage:
  deploy:
    CRON_CONSUMERS_RUNNER:
      cron_run: true
      max_messages: 1000
      consumers: []

By default, the deployment process overwrites the corresponding settings in the env.php file. See Manage message queues in the Commerce Configuration Guide for on-premises Adobe Commerce.

CONSUMERS_WAIT_FOR_MAX_MESSAGES

Configure how consumers process messages from the message queue by choosing one of the following options:

stage:
  deploy:
    CONSUMERS_WAIT_FOR_MAX_MESSAGES: false

CRYPT_KEY

When you move the database from one environment to another without an installation process, you need the corresponding cryptographic information. Adobe Commerce uses the encryption key value set in the Cloud Console as the crypt/key value in the env.php file.

DATABASE_CONFIGURATION

If you defined a database in the relationships property of the .magento.app.yaml file, you can customize your database connections for deployment.

stage:
  deploy:
    DATABASE_CONFIGURATION:
      some_config: 'some_value'

By default, the deployment process overwrites all settings in the env.php file; however, you can choose to merge one or more values for a service configuration without overwriting all values.

Set the _merge option to one of the following:

The following example merges new values to an existing configuration:

stage:
  deploy:
    DATABASE_CONFIGURATION:
      some_config: 'some_new_value'
      _merge: true

Also, you can configure a table prefix.

The following example uses the ece_ table prefix with default connection settings instead of using the _merge option:

stage:
  deploy:
    DATABASE_CONFIGURATION:
      connection:
        default:
          username: user
          host: host
          dbname: magento
          password: password
      table_prefix: 'ece_'

Sample output:

MariaDB [main]> SHOW TABLES;
+-------------------------------------+
| Tables_in_main                      |
+-------------------------------------+
| ece_admin_passwords                 |
| ece_admin_system_messages           |
| ece_admin_user                      |
| ece_admin_user_session              |
| ece_adminnotification_inbox         |
| ece_amazon_customer                 |
| ece_authorization_rule              |
| ece_cache                           |
| ece_cache_tag                       |
| ece_captcha_log                     |
...

ELASTICSUITE_CONFIGURATION

Retains customized Elastic Suite service settings between deployments and uses it in the ‘system/default/smile_elasticsuite_core_base_settings’ section of the main Elastic Suite configuration. If the Elastic Suite composer package is installed, it is configured automatically.

stage:
  deploy:
    ELASTICSUITE_CONFIGURATION:
      es_client:
        servers: 'remote-host:9200'
      indices_settings:
        number_of_shards: 1
        number_of_replicas: 0

     indices_settings:
           number_of_shards: 1
           number_of_replicas: 2

By default, the deployment process overwrites all settings in the env.php file; however, you can choose to merge one or more values for a service configuration without overwriting all values.

Set the _merge option to one of the following:

The following example merges a new value to the existing configuration:

stage:
  deploy:
    ELASTICSUITE_CONFIGURATION:
      indices_settings:
        number_of_shards: 1
        number_of_replicas: 2
      _merge: true

Known limitations:

ENABLE_GOOGLE_ANALYTICS

Enables and disables Google Analytics when deploying to Staging and Integration environments. By default, Google Analytics is true only for the Production environment. To enable Google Analytics in the Staging and Integration environments, set this value to true.

Add the ENABLE_GOOGLE_ANALYTICS environment variable to the deploy stage in the .magento.env.yaml file:

stage:
  deploy:
    ENABLE_GOOGLE_ANALYTICS: true

FORCE_UPDATE_URLS

On deployment to Pro or Starter Staging and Production environments, this variable replaces Adobe Commerce base URLs in the database with the project URLs specified by the MAGENTO_CLOUD_ROUTES variable. To override the default behavior of the UPDATE_URLS deploy variable, use this setting.

stage:
  deploy:
    FORCE_UPDATE_URLS: true

LOCK_PROVIDER

The lock provider prevents duplicate cron jobs and cron groups from running. Adobe Commerce on Cloud supports the file and db lock providers.

In Pro Staging and Production environments, MAGENTO_CLOUD_LOCKS_DIR configures the file provider. You cannot override this setting. In Pro Integration and Starter environments, ece-tools sets the db provider by default. To optimize local performance and mirror the production architecture, set the provider to file in those environments.

stage:
  deploy:
    LOCK_PROVIDER: 'file'

MYSQL_USE_SLAVE_CONNECTION

Adobe Commerce can read multiple databases asynchronously. Set to true to use a read-only connection to the database automatically to receive read-only traffic on a non-master node. This connection improves performance through load balancing, because only one node handles read-write traffic. To remove any existing read-only connection array from the env.php file, set to false.

stage:
  deploy:
    MYSQL_USE_SLAVE_CONNECTION: true

When the MYSQL_USE_SLAVE_CONNECTION variable is set to true, the system sets the synchronous_replication parameter to true by default in the env.php file on Pro Staging and Production environments. When the MYSQL_USE_SLAVE_CONNECTION is set to false, the synchronous_replication parameter is not configured.

QUEUE_CONFIGURATION

Use this environment variable to retain customized queue service settings between deployments. This variable supports both AMQP (for RabbitMQ) and STOMP (for ActiveMQ Artemis) protocols. For example, if you prefer using an existing message queue service instead of relying on the cloud infrastructure to create it for you, use the QUEUE_CONFIGURATION environment variable to connect it to your site:

stage:
  deploy:
    QUEUE_CONFIGURATION:
      amqp:
        host: test.host
        port: 1234
      amqp2:
        host: test.host2
        port: 12345
      mq:
        host: mq.host
        port: 1234

For ActiveMQ Artemis using STOMP protocol:

stage:
  deploy:
    QUEUE_CONFIGURATION:
      stomp:
        host: activemq.host
        port: 61616
        user: username
        password: password

By default, the deployment process overwrites all settings in the env.php file; however, you can choose to merge one or more values for a service configuration without overwriting all values.

Set the _merge option to one of the following:

The following example merges new values to an existing configuration:

stage:
  deploy:
    QUEUE_CONFIGURATION:
      _merge: true
      amqp:
        host: changed1.host
        port: 5672
      amqp2:
        host: changed2.host2
        port: 12345
      mq:
        host: changedmq.host
        port: 1234

REDIS_BACKEND

Specifies the backend model configuration for the Redis cache.

Redis cache is not supported for Adobe Commerce 2.4.9 or for patch releases later than 2.4.5-p16, 2.4.6-p14, 2.4.7-p9, and 2.4.8-p4. For those releases, use Valkey and the corresponding VALKEY_BACKEND configuration. Always verify the supported cache service in the system requirements.

For Redis-supported releases, the available backend models include:

The following example enables the remote-synchronized cache backend and L2 cache:

stage:
  deploy:
    REDIS_BACKEND: '\Magento\Framework\Cache\Backend\RemoteSynchronizedCache'

REDIS_USE_SLAVE_CONNECTION

Adobe Commerce can read multiple Redis instances asynchronously. Set this variable to true to use a read-only connection to a Redis replica for read traffic while the primary instance handles read-write traffic. To remove an existing read-only connection array from env.php, set it to false.

stage:
  deploy:
    REDIS_USE_SLAVE_CONNECTION: true

You must have a Redis service configured in the .magento.app.yaml and services.yaml files.

ECE-Tools version 2002.0.18 and later uses more fault-tolerant settings. If Adobe Commerce cannot read data from the Redis replica, it falls back to the Redis primary instance.

The read-only connection is not available in the Integration environment. If you use CACHE_CONFIGURATION, merge changes into the generated configuration and verify that the resulting configuration retains the replica connection.

VALKEY_BACKEND

VALKEY_BACKEND specifies the backend model for Valkey cache configuration. The default value uses a legacy Redis-compatible class name; it does not mean that the service must be Redis.

For Adobe Commerce versions earlier than 2.4.9 that support Valkey, the backend models include:

Adobe Commerce 2.4.9 and later also support symfony_l2, the Symfony Cache-based L2 implementation. symfony_l2 is supported with Valkey only.

Configure remote synchronized cache

For Adobe Commerce 2.4.8, use the following configuration when the remote-synchronized cache implementation is appropriate:

stage:
  deploy:
    VALKEY_BACKEND: '\Magento\Framework\Cache\Backend\RemoteSynchronizedCache'

Specifying the remote-synchronized backend enables L2 cache, and ece-tools generates the cache configuration automatically. See the example configuration file. To customize the generated configuration, use CACHE_CONFIGURATION.

Configure modern Symfony L2 cache implementation

For Adobe Commerce 2.4.9 and later, use the Symfony L2 implementation:

stage:
  deploy:
    VALKEY_BACKEND: 'symfony_l2'

Specifying symfony_l2 as the Valkey backend model enables L2 cache, and ece-tools generates the L2 cache configuration automatically from your Valkey service connection details, including the default and stale_cache_enabled frontends. Define CACHE_CONFIGURATION only when you need to customize supported backend options, such as the local cache directory. See Symfony L2 cache implementation in the Adobe Commerce Configuration Guide.

VALKEY_USE_SLAVE_CONNECTION

Adobe Commerce can read multiple Valkey instances asynchronously. Set VALKEY_USE_SLAVE_CONNECTION to true to use a read-only connection to a Valkey replica for read-only traffic while the primary instance handles read-write traffic. This connection improves performance through load balancing, because only one node handles read-write traffic. To remove an existing read-only connection array from env.php, set it to false.

stage:
  deploy:
    VALKEY_USE_SLAVE_CONNECTION: true

You must have a Valkey service configured in .magento.app.yaml and .magento/services.yaml. Whether a replica connection is available depends on the project topology and the installed ece-tools version.

Before relying on this setting, inspect the decoded MAGENTO_CLOUD_RELATIONSHIPS value and confirm that a replica relationship is present. For example:

echo "$MAGENTO_CLOUD_RELATIONSHIPS" | base64 -d | json_pp

For symfony_l2, replica support requires the relevant ece-tools and Cloud Patches updates. Update to the latest ece-tools version before enabling this setting. If no replica relationship is present after redeployment, contact Adobe Commerce Support.

When using CACHE_CONFIGURATION, merge supported overrides into the generated configuration instead of replacing the generated connection structure.

RESOURCE_CONFIGURATION

Maps a resource name to a database connection. This configuration corresponds to the resource section of the env.php file.

By default, the deployment process overwrites all settings in the env.php file; however, you can choose to merge one or more values for a service configuration without overwriting all values.

Set the _merge option to one of the following:

The following example merges new values to an existing configuration:

stage:
  deploy:
    RESOURCE_CONFIGURATION:
      _merge: true
      default_setup:
        connection: default

SCD_COMPRESSION_LEVEL

Specifies which gzip compression level (0 to 9) to use when compressing static content. Set it to 0 to disable compression.

stage:
  deploy:
    SCD_COMPRESSION_LEVEL: 5

SCD_COMPRESSION_TIMEOUT

When the time it takes to compress the static assets exceeds the compression timeout limit, it interrupts the deployment process. Set the maximum execution time, in seconds, for the static content compression command.

stage:
  deploy:
    SCD_COMPRESSION_TIMEOUT: 800

SCD_MATRIX

You can configure multiple locales per theme. This customization speeds up the deployment process by reducing the number of unnecessary theme files. For example, you can deploy the magento/backend theme in English and a custom theme in other languages.

The following example deploys the Magento/backend theme with three locales:

stage:
  deploy:
    SCD_MATRIX:
      "magento/backend":
        language:
          - en_US
          - fr_FR
          - af_ZA

Also, you can choose to not deploy a theme:

stage:
  deploy:
    SCD_MATRIX:
      "magento/backend": [ ]

SCD_MAX_EXECUTION_TIME

Allows you to increase the maximum expected execution time for static content deployment.

By default, Adobe Commerce sets the maximum expected execution to 900 seconds, but some scenarios require more time to complete the static content deployment for a Cloud project.

stage:
  deploy:
    SCD_MAX_EXECUTION_TIME: 3600

SCD_NO_PARENT

On the deploy phase, set SCD_NO_PARENT: true so that the generation of static content for parent themes does not occur during the deploy phase. This setting minimizes deployment time and prevents site downtime that can occur if the static content build fails during the deployment. See Static content deployment.

stage:
  deploy:
    SCD_NO_PARENT: true

SCD_STRATEGY

Allows you to customize the deployment strategy for static content. See Deploy static view files.

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

stage:
  deploy:
    SCD_STRATEGY: "compact"

SCD_THREADS

Sets the number of threads for static content deployment. The default value is set based on the detected CPU thread count and does not exceed a value of 4. Increasing the number of threads speeds up static content deployment. Decreasing the number of threads slows it down. You can set the thread value, for example:

stage:
  deploy:
    SCD_THREADS: 2

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

SEARCH_CONFIGURATION

Use this environment variable to retain customized search service settings between deployments. For example:

Elasticsearch configuration:

stage:
  deploy:
    SEARCH_CONFIGURATION:
      engine: elasticsearch
      elasticsearch_server_hostname: http://elasticsearch.internal
      elasticsearch_server_port: '9200'
      elasticsearch_index_prefix: magento2
      elasticsearch_server_timeout: '15'

OpenSearch configuration (for Commerce 2.4.6 and later):

stage:
  deploy:
    SEARCH_CONFIGURATION:
      engine: opensearch
      opensearch_server_hostname: 'http://opensearch.internal'
      opensearch_server_port: '9200'
      opensearch_index_prefix: 'magento2'
      opensearch_server_timeout: '15'

By default, the deployment process overwrites all settings in the env.php file; however, you can choose to merge one or more values for a service configuration without overwriting all values.

Set the _merge option to one of the following:

The following example merges a new value to the existing configuration:

stage:
  deploy:
    SEARCH_CONFIGURATION:
      engine: elasticsearch
      elasticsearch_server_port: '9200'
      _merge: true

SESSION_CONFIGURATION

Use SESSION_CONFIGURATION to configure session storage. The example below uses the Redis-compatible session configuration structure. Use it only with the session-storage naming and service combination supported by the exact Commerce release. For Valkey-backed sessions, follow the Valkey session-storage example.

Do not assume that cache variables such as VALKEY_BACKEND or REDIS_BACKEND configure sessions. Cache and session configuration are independent. On Cloud projects, use the service relationship and generated configuration where possible; do not hard-code environment-specific values without replacing the example host and port.

stage:
  deploy:
    SESSION_CONFIGURATION:
      redis:
        bot_first_lifetime: 100
        bot_lifetime: 10001
        database: 0
        disable_locking: 1
        host: 'redis.internal'
        max_concurrency: 10
        max_lifetime: 10001
        min_lifetime: 100
        port: 6379
      save: redis

Replace redis.internal and 6379 with the session-service host and port for the target environment when the deployment configuration requires explicit connection details.

By default, the deployment process overwrites all settings in the env.php file; however, you can choose to merge one or more values for a service configuration without overwriting all values.

Set the _merge option to one of the following:

The following example merges a new value to the existing configuration:

stage:
  deploy:
    SESSION_CONFIGURATION:
      _merge: true
      redis:
        max_concurrency: 10

SKIP_SCD

Set to true to skip static content deployment during the deploy phase.

On the deploy phase, set SKIP_SCD: true so that the static content build does not happen during the deploy phase. This setting minimizes deployment time and prevents site downtime that can occur if the static content build fails during the deployment. See Static content deployment.

stage:
  deploy:
    SKIP_SCD: true

UPDATE_URLS

On deployment, replace Adobe Commerce base URLs in the database with the project URLs specified by the MAGENTO_CLOUD_ROUTES variable. This configuration is useful for local development, where base URLs are set up for your local environment. When you deploy to a Cloud environment, the URLs update so you can access your storefront and Admin using the project URLs.

If you must update URLs when deploying to Pro or Starter Staging and Production environments, use the FORCE_UPDATE_URLS variable.

stage:
  deploy:
    UPDATE_URLS: false

USE_LUA

Controls the use_lua cache backend option in env.php for the default cache frontend (and, when using the symfony_l2 backend, the stale_cache_enabled frontend’s remote backend options). This option is not applied to the page_cache frontend.

Use the default value false unless Adobe support explicitly directs otherwise.

stage:
  deploy:
    USE_LUA: false

LUA_KEY

The LUA_KEY variable is deprecated. If LUA_KEY is included in .magento.env.yaml, remove it during migration. Use the USE_LUA and USE_LUA_ON_GC variables instead.

USE_LUA_ON_GC

Controls the use_lua_on_gc cache backend option in env.php for the default cache frontend (and, when using the symfony_l2 backend, the stale_cache_enabled frontend’s remote backend options) for garbage collection. This option is not applied to the page_cache frontend.

Use the default value true to preserve atomic cache tag cleanup during the backend_clean_cache cron job.

stage:
  deploy:
    USE_LUA_ON_GC: true

VERBOSE_COMMANDS

Enable or disable the Symfony debug verbosity level for bin/magento CLI commands performed during the deployment phase.

Choose the level of detail provided in the logs:

stage:
  deploy:
    VERBOSE_COMMANDS: "-vv"