Documentation Commerce Commerce on Cloud Infrastructure Guide

Upgrade project to use ECE-Tools package

Last update: Thu Jul 18 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Topics:
Cloud
Install

CREATED FOR:

Admin
Developer

Adobe deprecated the magento/magento-cloud-configuration and magento/ece-patches packages in favor of the ece-tools package, which simplifies many cloud processes. If you use an older Adobe Commerce on cloud infrastructure project that does not contain the ece-tools package, then you must perform a one-time, manual upgrade process to your project.

WARNING

If your project contains the ece-tools package, you can skip the following upgrade. To verify, retrieve the Commerce version using the php vendor/bin/ece-tools -V command at your local project root directory.

This project upgrade process requires you to update the magento/magento-cloud-metapackage version constraint in the composer.json file at the root directory. This constraint enables updates for Adobe Commerce on cloud infrastructure metapackages—including removing deprecated packages—without upgrading your current Adobe Commerce version.

TIP

Before beginning an upgrade or a patching process, create an active branch from the Integration environment and check out the new branch to your local workstation. Dedicating a branch to the upgrade or the patch process helps to avoid interference with your work in progress.

Remove deprecated packages

Before performing an upgrade to use the ece-tools package, check the composer.lock file for the following deprecated packages:

magento/magento-cloud-configuration
magento/ece-patches

Update the metapackage

Each Adobe Commerce version requires a different constraint based on the following:

>=current_version <next_version

For current_version, specify the Adobe Commerce version to install.
For next_version, specify the next patch version after the value specified in current_version.

If you want to install Adobe Commerce 2.3.5-p2, set current_version to 2.3.5 and the next_version to 2.3.6. The constraint ">=2.3.5 <2.3.6" installs the latest available package for 2.3.5.

You can always find the latest metapackage constraint in the magento-cloud template.

The following example places a constraint for the Adobe Commerce on cloud infrastructure metapackage to any version greater than or equal to the current version 2.4.7 and lower than next version 2.4.8:

"require": {
    "magento/magento-cloud-metapackage": ">=2.4.7 <2.4.8"
},

Upgrade the project

To upgrade your project to use the ece-tools package, you must update the metapackage and the .magento.app.yaml hooks properties, and perform a Composer update.

To upgrade project to use ece-tools:

Update the magento/magento-cloud-metapackage version constraint in the composer.json file.

code language-bash
`composer require "magento/magento-cloud-metapackage":">=2.4.7 <2.4.8" --no-update`

Update the metapackage.

code language-bash
`composer update magento/magento-cloud-metapackage`

Modify the hook commands in the magento.app.yaml file.

code language-yaml

code language-yaml
hooks: # We run build hooks before your application has been packaged. build: \| set -e php ./vendor/bin/ece-tools run scenario/build/generate.xml php ./vendor/bin/ece-tools run scenario/build/transfer.xml # We run deploy hook after your application has been deployed and started. deploy: \| php ./vendor/bin/ece-tools run scenario/deploy.xml # We run post deploy hook to clean and warm the cache. Available with ECE-Tools 2002.0.10. post_deploy: \| php ./vendor/bin/ece-tools run scenario/post-deploy.xml

hooks:
    # We run build hooks before your application has been packaged.
    build: |
        set -e
        php ./vendor/bin/ece-tools run scenario/build/generate.xml
        php ./vendor/bin/ece-tools run scenario/build/transfer.xml
    # We run deploy hook after your application has been deployed and started.
    deploy: |
        php ./vendor/bin/ece-tools run scenario/deploy.xml
    # We run post deploy hook to clean and warm the cache. Available with ECE-Tools 2002.0.10.
    post_deploy: |
        php ./vendor/bin/ece-tools run scenario/post-deploy.xml

Check for and remove the deprecated packages. The deprecated packages can prevent a successful upgrade.

code language-bash
`composer remove magento/magento-cloud-configuration`

code language-bash
`composer remove magento/ece-patches`

It may be necessary to update the ece-tools package.

code language-bash
`composer update magento/ece-tools`

Add and commit the code changes. In this example, the following files were updated:

code language-none
`.magento.app.yaml composer.json composer.lock`

Push your code changes to the remote server and merge this branch with the integration branch.

code language-bash
`git push origin <branch-name>`

recommendation-more-help

05f2f56e-ac5d-4931-8cdb-764e60e16f26