Release notes for ece-tools

The ece-tools package is compatible with Magento Commerce version 2.1.4 and later to provide a rich set of features you can use to manage your Magento Commerce Cloud project. It contains scripts and Magento Commerce Cloud commands designed to help manage your code and automatically build and deploy your projects.

You can list the available ece-tools commands using:

php ./vendor/bin/ece-tools list

The following updates describe the latest improvements to the ece-tools package, which uses the following version sequence: 200<major>.<minor>.<patch>. See Upgrades and patches for information about updating to the latest release of the ece-tools package.


New features

  • Docker Updates

    • Now the Docker generator uses the services specified in the and .magento/services.yaml configuration files when building your Docker environment. You can choose a different service version using build parameters.

    • Added PHP 7.2 image—Added support for PHP 7.2 in Cloud Docker; updated the Launch Docker configuration to include the docker:build --php option to specify the version of PHP compatible with your Magento Commerce version.

    • Added a Cron container based on the PHP-CLI image.

    • Added the following services to the Docker build:

      • RabbitMQ 3.5 and 3.7

      • ElasticSearch 1.7, 2.4, and 5.2

      • Redis 3.2 and 4.0

    • Now you have the DB dump capability when using the Cloud Docker database container. Also, you can share files between a host machine and a container using the docker/mnt directory.

  • Configure with PHP constants—Added support for PHP constants in the .magento.env.yaml configuration file.

  • New Environment variable—By default, only the Production environment has Google Analytics enabled. You can enable Google Analytics on the Staging and Integration environments using the ENABLE_GOOGLE_ANALYTICS environment variable.

Resolved Issues

  • Fixed inconsistencies in the messages and log levels for build, deploy, and post-deploy phases. Increased beginning and ending log message levels from info to notice for all phases and sub-phases. Added beginning and ending log messages, where appropriate.

  • Fixed an issue involving cron processes that prevented the start of the post-deploy phase, when configured. Now, if you have the post-deploy hook enabled, the cron processes are enabled again at the beginning of the post-deploy phase.

  • Resolved an issue that prevented a successful installation of Magento when specifying a custom database configuration. Previously, the installation process used the database configuration from the MAGENTO_CLOUD_RELATIONSHIP variable even if you designated customized connection information in the DATABASE_CONFIGURATION environment variable.

  • Corrected the config:dump command so that it includes each website locale in the system section of the config.local.php file.

  • Fixed an issue that resulted in warm-up errors during the post-deploy phase by correcting the source base URL reference.

  • Fixed an issue that generated files improperly during the setup:di:compile process, which affected the Amazon Pay module.


New features

  • Verify Ideal State—The ideal-state wizard now verifies the current configuration during each deployment and provides clear instructions for updating the configuration to achieve a faster, zero-downtime deployment.

  • PCI Compliance—Updated the messaging protocols for Magento Commerce Cloud to require Transport Layer Security (TLS) version 1.2 when connecting with third-party messaging services. If you are using a message service that does not support TLS version 1.2, you must upgrade your service. Otherwise, the following error message displays when your Magento Commerce application tries to connect to the message server to send an email: Unable to connect via TLS.

  • Deployment improvement—Added validation to warn customers if a Staging or Production environment has dev, debug, or debug_logging options enabled to prevent performance issues caused by excessive logging activity.

Resolved Issues

  • Deployment fixes

    • Now maintenance mode is enabled at the start of the deploy phase and disabled at the end. If the deployment fails, the site remains in maintenance mode until the deployment issues are resolved.

    • Reworked the deploy phase validation checks to downgrade the error level for the following deployment issues from CRITICAL to WARNING so that the deployment completes. Previously, these issues caused the deployment to fail.

      • ADMIN_EMAIL is not set on upgrade.

      • ADMIN_EMAIL or ADMIN_USERNAME is associated with another account.

      • Environment configuration contains incorrect values for deploy or cloud variables.

      • The Elasticsearch version on the cloud infrastructure is incompatible with the version of the elasticsearch/elasticsearch module supported by Magento Commerce Cloud. See the Elasticsearch troubleshooting article in the Magento Support Knowledgebase.

    • Fixed an issue with the shared configuration settings in the app/etc/config.php file that caused recursion detected errors during deployment.

  • Cron-related fixes

    • Fixed a cron scheduling issue that prevented jobs from running if you specify a cron frequency other than the default (1 minute).

    • Fixed an issue in the deploy phase that allowed cron jobs to continue running during deployment, which can cause database locks and other critical issues. Now, all cron jobs are stopped before the deploy phase begins and restarted after the deployment completes.

    • Fixed the cron job workflow in versions 2.1.4 through 2.1.x to unlock frozen cron jobs so that they can be stopped before beginning deployment. Previously, a frozen cron job caused the deployment to stall.

  • Changed the format of the config.php file generated by the vendor/bin/ece-tools config:dump command to use short array syntax and 4-space indentation to comply with Magento coding standards.

  • Fixed a deployment error that occurs when the .magento.env.yaml contains {{base_url}} and {{unsecure_base_url}} placeholders for web configurations instead of the default URL configuration for a Magento Commerce Cloud project.


New features

  • Enable zero-downtime deployment—Now Magento Commerce Cloud queues requests with required database changes during deployment and applies the changes as soon as the deployment completes. Requests can be held for up to 5 minutes to ensure that no sessions are lost. See Static content deployment options to reduce deployment downtime on Cloud.

  • Docker Compose for Cloud—Made the following improvements to the Docker configuration process:

    • Added a command—docker:config:convert to convert PHP configuration files to Docker ENV format to simplify environment configuration. Now, you copy the PHP configuration files to the Docker directory and convert them to Docker ENV files. See Launch Docker.

    • The Magento Commerce Cloud installation process now supports deploying to both read-only and read-write file systems to more closely emulate the Cloud file system. See Configure Docker.

    • Redis service support—Added a Redis image, which is deployed to a Docker container and configured automatically to work with your Docker installation.

    • Varnish service support— Added a Varnish image, which is deployed automatically to a Docker container. After deployment, you can manually configure Varnish following Magento best practices. See Configure and use Varnish

    • Secure site access—Added SSL support to access your Magento Commerce store and Admin panel.

  • Improved Magento Commerce Cloud extension support—Downgraded the minimum version requirement for the guzzlehttp/guzzle package in the Magento Commerce Cloud composer.json file to version 6.2 so that the ece-tools package is compatible with more extensions.

  • Apply custom changes to your Magento Commerce application during the build phase—We split the build phase into two separate processes so that you can use hooks to apply custom changes to the generated static content before packaging the application for deployment. The build:generate process generates code, applies patches, and generates static content. The build:transfer process transfers the generated code and static content to the final destination. See Application hooks.

  • Environment configuration checks—Improved validation of the environment configuration to warn customers about version incompatibilities and configuration errors before building and deploying Magento Commerce Cloud.

    • Added version-specific validation to identify unsupported or deprecated environment variables and values.

    • Added an Elasticsearch compatibility check to warn users about Elasticsearch configuration issues. Now, the deployment fails if the version of Elasticsearch service on the server is incompatible with Magento Commerce. Previously, the deployment succeeded even if the Elasticsearch version was incompatible, which caused product catalog issues after site deployment.

      You can resolve the incompatibility by submitting a Support ticket to upgrade Elasticsearch to a compatible version. For Magento Commerce version 2.1.x and later, upgrade Elasticsearch to version 2.4. If you have Elasticsearch version 1.x or 2.x and do not want to upgrade, you can change the Magento Commerce elasticsearch/elasticsearch requirement in composer.json to elasticsearch/elasticsearch: "~2.0".

    • Improved validation of environment variables to identify configuration settings that can cause conflicts during the build, deploy, and post-deploy phases. For example, a warning message displays during the install and upgrade process if the global setting for static content deployment conflicts with settings on the build or deploy phase.

  • Environment variable updates—Changed the following environment variables:

    • SKIP_HTML_MINIFICATION global variable—Changed the default value to true to enable on-demand HTML content minification, which minimizes downtime when deploying to Staging and Production environments. This configuration is required for zero-downtime deployments.

    • CLEAN_STATIC_FILES deploy variable—Added the capability to manage the clean static files processing for static content generated during the build phase based on the CLEAN_STATIC_FILES environment variable setting. Previously, static content files generated during the build phase were always cleaned.

  • Logging—Made the following changes to improve log messages and reduce log size:

    • Deployment failure log entries now include the command output from the operations that cause the failures even if your environment configuration does not specify debug level logging. See MIN_LOGGING_LEVEL.

    • Added logging for deployment failures that occur when the generated factories required by some extensions cannot be generated correctly because the file system is in a read-only state.

    • Reduced the deploy log size and fixed formatting issues caused by setup commands that use the interactive progress bar.

    • Eliminated unnecessary verbosity and updated the priority levels for some log statements.

Resolved Issues

  • Cron-specific fixes

    • Changed the default cron job configuration settings for history lifetime from 3d (4320 min) to 1h (60 min) to prevent performance issues and deployment failures that can occur when the cron queue fills too quickly.

    • Improved the cron job management process during the deploy phase to prevent database locks and other critical issues. Now, all cron jobs stop during the deploy phase and restart after deployment completes.

    • Fixed an issue with the cron:unlock command so that it works in Magento Commerce v2.1. Previously, the command was supported only in v2.1.

  • Fixed a Sitemap processing issue in the ece-tools package that caused third-party extension conflicts after using the ece-tools package to apply recent patches that included Sitemap-related changes.

  • Fixed an issue with the static content compression process process (gzip) that caused not overwritten and no such file or directory errors when referencing the compressed file during the deployment process.

  • Fixed permission checks that caused Missing write permissions errors during the upgrade process.

  • Fixed an issue that prevented the php ./vendor/bin/ece-tools config:dump command from removing redundant sections from the config.local.php file during the dump process if the store locale is not specified. Now you can easily move your configuration files between environments. After you update to ece-tools v2002.0.13, regenerate older config.local.php files with the improved config:dump command. See Configuration management for store settings.

  • Fixed an issue that caused an error during the deploy phase if the route configuration in the .magento/routes.yaml file redirects from an apex domain to a www domain.

  • Fixed an issue with the _merge option for the SEARCH_CONFIGURATION variable that caused incorrect merge results if the updated .magento.env.yaml configuration file did not include the engine parameter value along with other updated values. Now, the merge operation correctly overwrites only the parameter values included in the updated .magento.env.yaml without requiring you to specify the engine parameter value.

  • Fixed a Redis configuration issue that incorrectly enabled session locking for Magento Commerce Cloud versions 2.1.11 and later, which can cause slow performance and timeouts. Now, session locking is disabled by default. The issue was caused by a change in the default behavior of the disable_locking parameter introduced in v1.3.4 of the Redis session handler package. See colinmollenhour/php-redis-session-abstract package.


Theece-toolsversion 2002.0.12 now supports Magento 2.1.14.

New features

  • Docker Compose for Cloud—Added a new command—docker:build—to generate a Docker Compose configuration from the Cloud ece-tools repository.

  • Change Locales—Now you can change store locale without the exporting and importing configuration process. While Magento is in Production and the SCD_ON_DEMAND is enabled, the Magento store and admin locale options are available.

  • Site map and Robots—Created a new workflowto add a robots.txt file and generate a sitemap.xml file for a single domain configuration without requiring a change to the infrastructure.

  • Wizards—Added two new wizards to help you with Cloud configuration:

    • ideal-state—configure the ideal state for minimal deployment downtime
    • master-slave—configure load balancing for database and Redis
  • Module Refresh—Added a new Cloud command—module:refresh—to enable modules that were disabled or not explicitly enabled, similar to the way that it is done automatically during a build. See Build and deploy on local in Build phase.

  • Added the ability to choose to merge or overwrite configuration for services using the _merge option in CACHE, SESSION, QUEUE, and SEARCH configurations.

  • Environment Configuration sample file—We added a .magento.env.yaml sample file to the ece-tools package that includes a detailed description and possible values for each environment variable.

    • We also added a deep validation for the .magento.env.yaml configuration that prevents failures in the deployment process caused by unexpected values. When a failure occurs, you now receive a detailed error message that begins with: Environment configuration is not valid. Please correct .magento.env.yaml file with next suggestions:

  • Added the following Environment variables:
    • Now you can define multiple locales for each theme using the new SCD_MATRIX environment variable, which reduces the amount of theme files to deploy.

    • Added the DATABASE_CONFIGURATION environment variable to customize your database connections for deployment.

    • The new MIN_LOGGING_LEVEL variable overrides the minimum logging level for all output streams without making changes to the code.

Resolved issues

  • Fixed an issue that caused downtime between the deploy and post-deploy phase. Now, the post_deploy phase begins immediately after the deploy phase ends.

  • Fixed an issue that did not clean the successful cron jobs, those with status = success, from the schedule.

  • Fixed an issue with the post_deploy hook that cleared the cache in the deploy phase instead of the post-deploy phase of the project.

  • Fixed an issue when using SCD with multiple locales, which generated the same js-translation.json file for each locale.

  • Optimized the db:dump command in the ece-tools package to avoid locking tables and increase speed.


Theece-toolsversion 2002.0.11 now supports Magento 2.1.13.

New features

  • Configuring read-only connections to non-master nodes—This release adds the ability to configure a read-only connection to a non-master node to receive read-only traffic (for Redis and for MariaDB).
  • Configuration Wizard—Added a new wizard to help verify your configuration for static content deployment. See Smart wizards.

  • Symfony Console support—Added support for Symfony Console 4 with Magento 2.3.

  • Cron scheduling optimizations—Improved the queue management and enhanced logging to help with debugging cron-related issues.

Resolved issues

  • Deployment validation fails if an ADMIN_EMAIL or ADMIN_USERNAME value is the same as an existing Magento administrator account.

  • Removed SOLR support for 2.2.x versions. 2.1.x versions retain the ability to enable SOLR.

  • The first installation of the Staging & Production environments of a PRO project now includes different index prefixes for ElasticSearch to prevent possible conflicts while identifying records belonging to each environment.

  • Fixed an issue that interrupted the build phase for legacy architecture during static content deployment.

  • Cron-specific ImprovementsRe-worked the cron implementation:
    • Fixed an issue that caused the cron queue to fill quickly. Now it clears the outdated cron jobs in a more reliable way.
    • Re-organized the sequence of cron jobs so that all jobs in separate threads launch prior to the general group.
    • Improved logging to better assist in debugging cron issues.
    • NOTE—This release addresses many cron-related issues. If you currently use some cron-related patches in m2-hotfixes, remove them.
  • SCD-specific improvements
    • You can now use the VERBOSE_COMMANDS and the SCD_COMPRESSION_LEVEL environment variables during both build and deploy phases.

    • Fixed an issue that caused deployment to fail with a random error when encountering an unexpected value for the SCD_COMPRESSION_LEVEL environment variable. Improved the configuration validation to provide meaningful notifications. See SCD_COMPRESSION_LEVEL for acceptable values.

    • Fixed the behavior of the SCD_COMPRESSION_LEVEL environment variable configuration flow so the overrides work as expected.

    • Fixed an issue that prevented the configuration of the SCD_THREADS environment variable in the .magento.env.yaml file deploy stage.


New features

  • Static Content Deployment (SCD)—There is a new, alternative deployment process to generate static content when requested (on-demand). This decreases downtime and improves cache handling by generating the most critical assets.

    • New environment variable—Added the SCD_ON_DEMAND global environment variable to generate static content when requested.

    • Post-deploy hook—Added a post_deploy hook for the file that clears the cache and pre-loads (warms) the cache after the container begins accepting connections. It is available only for Pro projects that contain Staging and Production environments in the Project Web UI and for Starter projects. Although not required, this works in tandem with the SCD_ON_DEMAND environment variable.

  • Optimization—Optimized moving or copying files during deployment to improve deployment speed and decrease loads on the file system.

  • Deployment Logging—Added the ability to enable Syslog and Graylog Extended Log Format (GELF) handlers for outputting logs during the deployment process. See Logging handlers.

  • Added the following Environment variables:
    • CRYPT_KEY—Provide a cryptographic key to another environment when moving a database.

    • SKIP_HTML_MINIFICATIONGlobal environment variable that skips copying the static view files in the var/view_preprocessed directory and generates minified HTML when requested.

    • SCD_ON_DEMANDGlobal environment variable to generate static content when requested.

    • WARM_UP_PAGES—You can list the pages to use to pre-load the cache. Available in the new Post-deploy variables.

Resolved issues

  • We fixed an issue that involved a locally applied patch breaking the deployment on an instance. Now,ece-toolscan detect that a patch has been applied.

  • Fixed a conflict between JavaScript bundling and Gzip functionality. Now these features work correctly together.

  • Fixed an issue that caused c CLI commands to fail when using earlier PHP 7.0.x versions.

  • Fixed a Redis session locking issue that caused an Admin login delay. Also, the fix is available for 2.1.x.


You must upgrade the Magento Commerce Cloud metapackage to get this and all future updates.

New features

  • ece-tools—The ece-tools package now supports Magento 2.1.x. You must upgrade to ece-tools to use these features.

  • Redis configuration—You can now configure Redis page and default cache and Redis session storage using an environment variable.

  • Search, AMQP, and Redis service improvements—We unified the service configuration flow so that it now behaves the same way for all services. Manually editing the env.php file to configure services is no longer supported. You must use environment variables or the .magento.env.yaml file instead.

  • Environment variables

    • The use of env:STATIC_CONTENT_THREADS was deprecated and will be removed in a future release. Use the STATIC_CONTENT_THREADS environment variable instead.

    • The STATIC_CONTENT_EXCLUDE_THEMES environment variable was deprecated. You must use the SCD_EXCLUDE_THEMES environment variable instead.

  • Logging—We simplified logging around built-in patching operations.

Resolved issues

  • We removed developer mode support and the APPLICATION_MODE environment variable because they were causing unexpected behavior.

  • We fixed an issue that was causing static content deployment failures related to Redis. Now, multi-threaded static content deployment runs as designed.

  • We fixed an issue that was preventing users from saving modifications to configuration fields in the Admin, which are marked as sensitive after running the app:config:dump command.

  • We added support for an earlier version of symfony/yaml to fix conflicts with some packages, which are not yet compatible with the latest version.


We merged vendor/magento/ece-patches with vendor/magento/ece-tools in this release. You no longer need to update the vendor/magento/ece-patches package separately.

New features

  • Improved logging

    • We improved log messaging to provide better explanations when the build or deploy process overrides an environment variable.
    • You can now view installation and upgrade progress in real time. Tail the install_update.log file to view progress. For example,

      tail -f var/log/install_upgrade.log
  • New cron command—You can now unlock specific stuck cron jobs instead of stopping and re-launching all of them with the cron:unlock command. Not available in 2.1.

  • Unified configuration file—You can now configure build and deploy stages using a .magento.env.yaml file.

  • Backup configuration files—The deployment process now automatically creates a backup of the app/etc/env.php and app/etc/config.php configuration files after deployment. We also added a new CLI command to restore these configuration files from a backup.

  • Troubleshooting validation errors—We changed the command you must use to resolve validation errors when config.php does not contain enough data for static content deployment. Previously, the error message instructed you to run bin/magento app:config:dump. Now, you must run php ./vendor/bin/ece-tools config:dump.

  • New environment variables—You can now use environment variables to connect custom search and AMQP-based services to your site.

  • We implemented smart patching. Now the package applies patches based not on Magento Commerce Cloud version, but on patched package version.

Resolved issues

  • We fixed a logging issue that was causing build errors.

  • We fixed an issue that was causing timeout exceptions when running deployments in interactive mode.

  • We fixed an issue that was causing errors when using the compact strategy for static content generation. Not available in 2.1.

  • We fixed an issue that was preventing the deployment script from properly identifying staging and production environments.

  • We fixed an issue that was causing network issues to disrupt database connections and cause failures during the installation and upgrade process.

  • We fixed an issue preventing you from exporting the configuration files using app:config:dump more than once. Not available in 2.1.

  • We fixed a Redis session locking issue that caused an Admin login delay. Not available in 2.1.

  • We fixed an implementation issue related to versioning that was causing a conflict with other Composer-based patching modules.

  • We fixed an issue that was causing PHP memory issues during import.

  • Removed patch; fixing bug in colinmollenhour/credis v1.6 to enable support for Magento Commerce Cloud 2.2.1. Not available in 2.1.


Resolved issues

  • We removed var/view_preprocessed symlinking to fix an issue that was causing JavaScript minification conflicts.


Resolved issues

  • We fixed an issue that was causing gzip errors when a file or directory name contains spaces.

  • We fixed an issue that was preventing deployment scripts from properly recognizing and enabling module dependencies.


New features

  • Configure a cron consumer with an environment variable—You can now configure cron consumers using the new CRON_CONSUMERS_RUNNER environment variable.

  • Configuration scanning—We now scan for critical components during the build/deploy process and halt the process if the scan fails, which prevents unnecessary downtime due to the site being in maintenance mode.

  • Build/deploy notifications—We added a new configuration file that you can use to set up Slack and/or email notifications for build/deploy actions in all your environments.

  • Static content compression—We now compress static content using gzip during the build and deploy phases. This compression, coupled with Fastly compression, helps reduce the size of your store and increase deployment speed. If necessary, you can disable compression using a build option or deploy variable. See the following topics for more information:

  • Configuration management—We now auto-generate an app/etc/config.php file in your Git repository during the build phase if it doesn’t already exist. The auto-generated file includes only a list of modules and extensions. If the file already exists, the build phase continues as normal. If you follow Configuration Management at a later time, the commands update the file without requiring additional steps. Refer to Deployment process for more information.

  • Database dumps—We added a new magento/ece-tools CLI command for creating database dumps in all environments. For Pro plan Production environments, this command only dumps from one of three high-availability nodes, so production data written to a different node during the dump may not be copied. We recommend putting the application in maintenance mode before doing a database dump in Production environments. See Snapshots and backup management for more information.

  • Cron interval limitations lifted—The default cron interval for all environments provisioned in the us-3, eu-3, and ap-3 regions is 1 minute. The default cron interval in all other regions is 5 minutes for Pro Integration environments and 1 minute for Pro Staging and Production environments. To modify your existing cron jobs, edit your settings in or create a support ticket for Production/Staging environments. Refer to Set up cron jobs for more information.

Resolved issues

  • We fixed an issue that was causing long deploy times due to the deploy process invoking the cache-clean operation before static content deployment.

  • We fixed an issue causing errors during the static content generation step of deployment on Production environments.

  • We fixed an issue preventing some magento/ece-tools commands from logging output to stderr.

  • We fixed an issue preventing base URL values in env.php from being updated in forked branches.

  • We fixed an issue causing the magento setup:install command to add an unsecure prefix (http://) to secure base URLs.

  • We fixed an issue preventing patch errors from causing deployment failures.

  • We fixed an issue preventing ece-tools from halting execution and throwing an exception if no patches can be applied.

  • We fixed an issue causing errors when loading the storefront after enabling HTML minification in the Magento Admin.


Resolved issues


Resolved issues

  • We fixed an issue that was causing pages to time out because Redis was taking too long to read/write. You can now use the disable_locking parameter in Redis configurations to prevent this issue.


Resolved issues

  • The RabbitMQ configuration process now obtains all required parameters automatically.


New features

  • Magento Commerce Cloud now supports scopes and static content deployment strategies. We have added the –s parameter with a default setting of quick for the static content deployment strategy. You can use the environment variable SCD_STRATEGY to customize and use these strategies with your build and deploy actions. This variable supports the options standard, quick, or compact. If you select compact, we override the STATIC_CONTENT_THREADS value with 1, which can slow deployment, especially in production environments. Not available in 2.1.

  • We have created a new log file on environments to capture and compile build and deploy actions. The file is located in the var/log/cloud.log file inside the Magento root application directory.

Resolved issues

  • Refactored the ece-tools package to make it compatible with Magento Commerce Cloud 2.2.0 and higher.

  • We fixed an issue that was preventing ece-tools from halting execution and throwing an exception if no patches can be applied.

  • We fixed an issue that was causing exceptions to be thrown when dependency injection (di) compilation is skipped during builds.

  • We fixed an issue that was causing the deploy process to overwrite custom Redis configurations in the env.php file.

  • We fixed an issue that was causing redirect loops due to disabled by default secure admin.


This package is no longer compatible with other versions of Magento Commerce Cloud and should not be used.

Initial release

Initial release of ece-tools for Magento Commerce Cloud 2.2.0.