Upgrade Magento version
You can upgrade the core Magento Commerce code base to version 2.2 from version 2.1.7 and later. If you need to upgrade from an older version, you must upgrade to a supported version first.
Prepare your environment with the following tasks:
- Upgrade your PHP version to 7.1 or later
- Create a new
- Update the
.magento.app.yamlfile with new settings for hooks and environment variables
- Verify or set the
- Upgrade to the latest supported version of Fastly
- Add the new generated directory to the
Before beginning an upgrade or a patching process, create an active branch from the Integration environment and checkout 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.
If you use a version of Magento Commerce Cloud that does not contain the
ece-tools package, then your project requires an upgrade. If you currently use the
ece-tools package and you need to update it, see Update ece-tools version.
Upgrade PHP version
Magento Commerce Cloud 2.2 supports PHP 7.1 and later. You can upgrade the version of PHP on your local development workspace.
- PHP information for your local Magento workstation
- Migrating PHP
- Magento 2.2.x technology stack requirements
For Pro projects created before October 23, 2017, you must open a support ticket to use PHP 7.1 on your Pro Staging and Production environments.
If you are upgrading from 2.1.4 or later to 2.2.X and use Configuration Management, you need to migrate the
config.local.php file. Previous versions with Configuration Management used a
config.local.php file for Configuration Management. Starting with 2.2.0, Configuration Management uses the
To create a temporary
- Create a copy of
config.local.phpfile and name it
- Add this file to the
- Add and commit the file to your branch.
- Push the file to your Integration branch.
- Continue with the upgrade process.
After you finish upgrading, you can remove the
config.php file and create a new, complete file. This file works exactly as
config.local.php, with additional settings including a list of your enabled modules, additional configurations, and a different name.
You can only delete this file to replace it this one time. After generating a correct
config.php file, you cannot delete the file to generate a new one. For more information, see Configuration Management and Pipeline Deployment.
Update the .magento.app.yaml file
If you are upgrading to 2.2.X, you need to also update your .magento.app.yaml or you may encounter errors. Magento Commerce Cloud 2.2.X has new settings in the file.
Update the PHP options.
Modify the hook commands in the
hooks: We run build hooks before your application has been packaged. build: | php ./vendor/bin/ece-tools build # We run deploy hook after your application has been deployed and started. deploy: | php ./vendor/bin/ece-tools deploy # 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 post-deploy
Add the following environment variables to the end of the
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'
Save the file. Do not commit or push changes to your branch yet.
Back up the database
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.
Back up code and media.
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 server.
Create a database dump.
- We recommend setting the application in maintenance mode before doing a database dump in Production environments.
- This creates an
dump-<timestamp>.sql.gzarchive file in your local project directory. See Snapshot and backup management.
Complete the upgrade
Change to your Magento root directory and set the upgrade version.
composer require magento/magento-cloud-metapackage <requiredversion> --no-update
Update the project.
Add, commit, and push code changes.
git add -A && git commit -m "Upgrade" && git push origin <branch name>
git add -Ais required to add all changed files to source control because of the way Composer marshals base packages. Both
composer updatemarshal files from the base package (
magento/magento2-ee-base) into the package root.
The files Composer marshals belong to the new version of Magento, to overwrite the outdated version of those same files. Currently, marshaling is disabled in Magento 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.
php bin/magento --version
Create a new config.php file
After upgrading, you need to create an updated
config.php file. Complete any additional configuration changes through the Magento Admin in your Integration environment.
From the terminal, use an SSH command to generate the
/app/etc/config.phpfile for the environment.
ssh <SSH URL> "<Command>"
For example for Pro, to run the
ssh <project-id-integration>@ssh.us.magentosite.cloud "php vendor/bin/m2-ece-scd-dump"
config.phpfile to your local workstations using
scp. You can only add this file to the branch locally.
rsync <SSH URL>:app/etc/config.php ./app/etc/config.php
Add, commit, and push code changes.
git add app/etc/config.php && git commit -m "Add system-specific configuration" && git push origin master
This generates an updated
/app/etc/config.phpfile with a module list and configuration settings.
For an upgrade, you delete the
config.php file. Once this file is added to your code, you should not delete it. If you need to remove or edit settings, you must manually edit the file to make changes.
Verify and upgrade your extensions
If you need to upgrade any third-party extensions and modules that support version 2.2, we recommend working in a new Integration branch with your extensions disabled. Review your third-party extension and module pages in Marketplace or other company sites to verify support for Magento Commerce and Magento Commerce Cloud version 2.2.
- Create a new 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.
We strongly recommend upgrading your Production environment before including the upgraded extensions in your go-live process.
We strongly recommend upgrading your Fastly module to v1.2.33 or later for Magento Commerce Cloud 2.2.
If the upgrade failed, you receive an error message in the browser indicating you cannot access your storefront or the Magento Admin pane:
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:
Using SSH, log in to the remote server and open the
Examine the logs to determine the source of the issue.
Add, commit, and push code changes.
git add -A && git commit -m "Fixed deployment failure" && git push origin <branch name>