Upgrade Commerce version
You can upgrade the Adobe Commerce code base to a newer version. Before upgrading your project, review the System requirements in the Installation guide for the latest software version requirements.
Depending on your project configuration, your upgrade tasks may include the following:
- Update services—such as MariaDB (MySQL), OpenSearch, RabbitMQ, and Redis—for compatibility with new Adobe Commerce versions.
- Convert an older configuration management file.
- Update the
.magento.app.yaml
file with new settings for hooks and environment variables. - Upgrade third-party extensions to the latest supported version.
- Update the
.gitignore
file.
Staging
and Production
environments only..magento.app.yaml
and services.yaml
files, and state the PHP version in the ticket. For self-service changes to PHP version, extensions, or environment settings, see PHP settings in Application configuration.Upgrade from older versions
If you are beginning an upgrade from a Commerce version older than 2.1, some restrictions in the Adobe Commerce code base can affect your ability to update to a specific ECE-Tools release or to upgrade to the next supported Commerce version. Use the following table to determine the best path:
ece-tools
package, then you must perform a one-time upgrade to your cloud project to remove deprecated packages. If you currently use the ece-tools
package and you need to update it, see Update the ECE-Tools package.Configuration management
Older versions of Adobe Commerce, such as 2.1.4 or later to 2.2.x or later, used a config.local.php
file for Configuration Management. Adobe Commerce version 2.2.0 and later use the config.php
file, which works exactly like the config.local.php
file, but it has different configuration settings that include a list of your enabled modules and additional configuration options.
When upgrading from an older version, you must migrate the config.local.php
file to use the newer config.php
file. Use the following steps to back up your configuration file and create one.
To create a temporary config.php
file:
-
Create a copy of
config.local.php
file and name itconfig.php
. -
Add this file to the
app/etc
folder of your project. -
Add and commit the file to your branch.
-
Push the file to your integration branch.
-
Continue with the upgrade process.
config.php
file and generate a new, complete file. You can only delete this file to replace it this one time. After generating a new, complete config.php
file, you cannot delete the file to generate a new one. See Configuration Management and Pipeline Deployment.Verify Zend Framework composer dependencies
When upgrading to 2.3.x or later from 2.2.x, verify that the Zend Framework dependencies have been added to the autoload
property of the composer.json
file to support Laminas. This plugin supports new requirements for the Zend Framework, which has migrated to the Laminas project. See Migration of Zend Framework to the Laminas Project on the Magento DevBlog.
To check the auto-load:psr-4
configuration:
-
On your local workstation, change to your project directory.
-
Check out your integration branch.
-
Open the
composer.json
file in a text editor. -
Check the
autoload:psr-4
section for the Zend plugin manager implementation for controllers dependency.code language-json "autoload": { "psr-4": { "Magento\\Framework\\": "lib/internal/Magento/Framework/", "Magento\\Setup\\": "setup/src/Magento/Setup/", "Magento\\": "app/code/Magento/", "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/" }, }
-
If the Zend dependency is missing, update the
composer.json
file:-
Add the following line to the
autoload:psr-4
section.code language-json "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/"
-
Update the project dependencies.
code language-bash composer update
-
Add, commit, and push code changes.
code language-bash git add -A
code language-bash git commit -m "Add Zend plugin manager implementation for controllers dependency for Laminas support"
code language-bash git push origin <branch-name>
-
Merge changes to the Staging environment, and then to Production.
-
Configuration files
Before upgrading the application, you must update your project configuration files to account for changes to the default configuration settings for Adobe Commerce on cloud infrastructure or the application. The latest defaults can be found in the magento-cloud GitHub repository.
.magento.app.yaml
Always review the values contained in the .magento.app.yaml file for your installed version, because it controls the way your application builds and deploys to the cloud infrastructure. The following example is for version 2.4.6 and uses Composer 2.2.21. The build: flavor:
property is not used for Composer 2.x; see Installing and using Composer 2.
To update the .magento.app.yaml
file:
-
On your local workstation, change to your project directory.
-
Open and edit the
magento.app.yaml
file. -
Update the PHP options.
code language-yaml type: php:8.2 build: flavor: none dependencies: php: composer/composer: '2.2.21'
-
Modify the
hooks
propertybuild
anddeploy
commands.code language-yaml hooks: # We run build hooks before your application has been packaged. build: | set -e composer install 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
-
Add the following environment variables to the end of the file.
For Adobe Commerce 2.2.x through 2.3.x–
code language-yaml variables: env: CONFIG__DEFAULT__PAYPAL_ONBOARDING__MIDDLEMAN_DOMAIN: 'payment-broker.magento.com' CONFIG__STORES__DEFAULT__PAYMENT__BRAINTREE__CHANNEL: 'Magento_Enterprise_Cloud_BT' CONFIG__STORES__DEFAULT__PAYPAL__NOTATION_CODE: 'Magento_Enterprise_Cloud'
For Adobe Commerce 2.4.x–
code language-yaml variables: env: CONFIG__DEFAULT__PAYPAL_ONBOARDING__MIDDLEMAN_DOMAIN: 'payment-broker.magento.com' CONFIG__STORES__DEFAULT__PAYPAL__NOTATION_CODE: 'Magento_Enterprise_Cloud'
-
Save the file. Do not commit or push changes to the remote environment yet.
-
Continue with the upgrade process.
composer.json
Before upgrading, always check that the dependencies in the composer.json
file are compatible with the Adobe Commerce version.
To update the composer.json
file for Adobe Commerce version 2.4.4 and later:
-
Add the following
allow-plugins
to theconfig
section:code language-json "config": { "allow-plugins": { "dealerdirect/phpcodesniffer-composer-installer": true, "laminas/laminas-dependency-plugin": true, "magento/*": true } },
-
Add the following plugin to the
require
section:code language-json "require": { "magento/composer-root-update-plugin": "^2.0.3" },
-
Add the following component to the
extra:component_paths
section:code language-json "extra": { "component_paths": { "tinymce/tinymce": "lib/web/tiny_mce_5" }, },
-
Save the file. Do not commit or push changes to your branch yet.
-
Continue with the upgrade process.
Project backup
We recommend creating a backup of your project before an upgrade. Use the following steps to back up your Integration, Staging, and Production environments.
To back up your integration environment database and code:
-
Create a local backup of the remote database.
code language-bash magento-cloud db:dump
note note NOTE The magento-cloud db:dump
command runs the mysqldump command with the--single-transaction
flag, which allows you to back up your database without locking the tables. -
Back up code and media.
code language-bash php bin/magento setup:backup --code [--media]
Optionally, you can omit
[--media]
if you have a large number of static files that are already in source control.
To back up your Staging or Production environment database before deploying:
-
Use SSH to log in to the remote environment.
-
Create a database dump. To choose a target directory for the DB dump, use the
--dump-directory
option.code language-bash vendor/bin/ece-tools db-dump
The dump operation creates a
dump-<timestamp>.sql.gz
archive file in your remote project directory. See Back up database.
Application upgrade
Review the service versions information for the latest software version requirements before upgrading your application.
To upgrade the application version:
-
On your local workstation, change to your project directory.
-
Set the upgrade version using the version constraint syntax.
code language-bash composer require "magento/magento-cloud-metapackage":">=CURRENT_VERSION <NEXT_VERSION" --no-update
note note NOTE You must use the version constraint syntax to successfully update the ece-tools
package. You can find the version constraint in thecomposer.json
file for the version of the application template you are using for the upgrade. -
Update the project.
code language-bash composer update
-
Add, commit, and push code changes.
code language-bash git add -A
code language-bash git commit -m "Upgrade"
code language-bash git push origin <branch-name>
git add -A
is required to add all changed files to source control because of the way Composer marshals base packages. Bothcomposer install
andcomposer update
marshal files from the base package (magento/magento2-base
andmagento/magento2-ee-base
) into the package root.The files that Composer marshals belong to the new version of Adobe Commerce, to overwrite the outdated version of those same files. Currently, marshaling is disabled in Adobe Commerce, so you must add the marshaled files to source control.
-
Wait for deployment to complete.
-
Verify the upgrade in your Integration, Staging, or Production environment by using SSH to log in and check the version.
code language-bash php bin/magento --version
Create a config.php file
As mentioned in Configuration management, after upgrading, you must create an updated config.php
file. Complete any additional configuration changes through the Admin in your integration environment.
To create a system-specific configuration file:
-
From the terminal, use an SSH command to generate the
/app/etc/config.php
file for the environment.code language-bash ssh <SSH-URL> "<Command>"
For example for Pro, to run the
scd-dump
on theintegration
branch:code language-bash ssh <project-id-integration>@ssh.us.magentosite.cloud "php vendor/bin/ece-tools config:dump"
-
Transfer the
config.php
file to your local workstations usingrsync
orscp
. You can only add this file to the branch locally.code language-bash rsync <SSH-URL>:app/etc/config.php ./app/etc/config.php
-
Add, commit, and push code changes.
code language-bash git add app/etc/config.php && git commit -m "Add system-specific configuration" && git push origin master
This generates an updated
/app/etc/config.php
file with a module list and configuration settings.
config.php
file. Once this file is added to your code, you should not delete it. If you must remove or edit settings, edit the file manually.Upgrade extensions
Review your third-party extension and module pages in Marketplace or other company sites and verify support for Adobe Commerce and Adobe Commerce on cloud infrastructure. If you must upgrade any third-party extensions and modules, Adobe recommends working in a new integration branch with your extensions disabled.
To verify and upgrade your extensions:
-
Create a branch on your local workstation.
-
Disable your extensions as needed.
-
When available, download extension upgrades.
-
Install the upgrade as documented by the third-party documentation.
-
Enable and test the extension.
-
Add, commit, and push the code changes to the remote.
-
Push to and test in your integration environment.
-
Push to the Staging environment to test in a pre-production environment.
Adobe strongly recommends upgrading your Production environment before including the upgraded extensions in your site launch process.
Troubleshoot upgrade
If the upgrade failed, you receive an error message in the browser indicating that you cannot access your storefront or the Admin panel:
There has been an error processing your request
Exception printing is disabled by default for security reasons.
Error log record number: <error-number>
To resolve the error:
-
On your local workstation, change to your project directory.
-
Use SSH to log in to the remote environment.
code language-bash magento-cloud ssh
-
Open the
./app/var/report/<error number>
file. -
Examine the logs and determine the source of the issue.
-
Add, commit, and push code changes.
code language-bash git add -A && git commit -m "Fixed deployment failure" && git push origin <branch-name>