PaaS only

Deploy variables

Last update: May 21, 2025

CREATED FOR:

  • Developer

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

  • Default—Not set
  • Version—Adobe Commerce 2.1.4 and later

Configure Redis page and default caching. When setting the cm_cache_backend_redis parameter, you must specify the server, port, and database options.

stage:
  deploy:
    CACHE_CONFIGURATION:
      frontend:
        default:
          backend: file
        page_cache:
          backend: 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:

  • true—Merge the configured service values with the environment variable values.
  • false—Overwrite the configured service values with the environment variable values.

The following example merges new values to an existing configuration:

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:

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 (not only from the allowed list), set the _custom_redis_backend option to true to enable the correct validation as in the following example:

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

CLEAN_STATIC_FILES

  • Default—true
  • Version—Adobe Commerce 2.1.4 and later

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.

  • true—Removes all existing static content before deploying the updated static content.
  • false—The deployment only overwrites existing static content files if the generated content contains a newer version.

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

  • Default—cron_run = false, max_messages = 1000
  • Version—Adobe Commerce 2.2.0 and later

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

  • cron_run—A boolean value that enables or disables the consumers_runner cron job (default = false).

  • max_messages—A number specifying the maximum number of messages each consumer must process before terminating (default = 1000). You can set the value to 0 to prevent the consumer from terminating.

  • consumers—An array of strings specifying which consumers to run. An empty array runs all consumers.

  • multiple_processes-A number specifying the number of processes to spawn for each consumer. Supported in Commerce 2.4.4 or greater.

NOTE
To return a list of message queue consumers, run the ./bin/magento queue:consumers:list command in the remote environment.

Example array that runs specific consumers and the multiple_processes to spawn for each consumer:

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

Example of an empty array that runs all consumers:

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

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