Upgrade Magento version

You can upgrade the core Magento Commerce code base to a newer version. It is best to review the summary of the updated technology stack before upgrading your project. If you need to upgrade from a version older than 2.1, you must upgrade to a supported version first. See Upgrades and patches for upgrade path details.

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 you must upgrade your project. If you currently use the ece-tools package and you need to update it, see Update ece-tools version.

Upgrading from older versions of the Magento application

If you are upgrading from 2.1.4 or later to 2.2.x or later, review the Magento technology stack requirements. Your upgrade tasks may include the following:

• Upgrade your PHP version
• Convert an older configuration management file
• Update the .magento.app.yaml file with new settings for hooks and environment variables
• Upgrade to the latest supported version of Fastly
• Update the .gitignore file

Configuration management

If you are upgrading from 2.1.4 or later to 2.2.x or later and use Configuration Management, you need to migrate the config.local.php file. Older versions used a config.local.php file for Configuration Management, but version 2.2.0 and later use the config.php file. This file works exactly as the config.local.php file, with additional settings that include a list of your enabled modules, additional configurations, and a different name.

To create a temporary config.php file:

1. Create a copy of config.local.php file and name it config.php.

2. Add this file to the app/etc folder.

3. Add and commit the file to your branch.

4. Push the file to your Integration branch.

5. Continue with the upgrade process.

After upgrading, you can remove the 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.

Update the configuration file

If you are upgrading from an older version of Magento to 2.2.x or later, you must also update your .magento.app.yaml file or you might encounter errors. Magento Commerce Cloud 2.2.x and later has new settings in the file.

To update the .magento.app.yaml file:

1. Update the PHP options.

   1
   type: php:<version>
   

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

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   hooks:
       # We run build hooks before your application has been packaged.
       build: |
           set -e
           php ./vendor/bin/ece-tools build:generate
           php ./vendor/bin/ece-tools build:transfer
       # 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
   

3. Add the following environment variables to the end of the magento.app.yaml file.

   1
   2
   3
   4
   5
   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'
   

4. Save the file. Do not commit or push changes to your branch yet.

5. Continue with the upgrade process.

Upgrading the Magento application

Review the Magento technology stack requirements before upgrading your Magento application.

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:

1. Create a local backup of the remote database.

   1
   magento-cloud db:dump
   

   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.

2. Back up code and media.

   1
   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:

1. Use SSH to log in to the remote server.

2. Create a database dump.

   1
   vendor/bin/ece-tools db-dump
   

• We recommend setting the application in maintenance mode before doing a database dump in Production environments.
• This creates an dump-<timestamp>.sql.gz archive file in your local project directory. See Snapshot and backup management.

Complete the upgrade

If you use PHP version 7.2, you must remove the mcrypt extension from the extensions section of the .magento.app.yaml file. For Pro projects, you need to create a support ticket to completely disable the mcrypt extension.

When upgrading to 2.3.x from 2.2.x, you must verify that the composer.json file contains "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/" in the "psr-4": section of the autoload property.

To upgrade the Magento version:

1. Change to your Magento root directory and set the upgrade version using the version constraint syntax.

   1
   composer require "magento/magento-cloud-metapackage":">=2.x.2 <2.x.3" --no-update
   

   You must use the version constraint syntax to successfully update the ece-tools package.

2. Update the project.

   1
   composer update
   

3. Add, commit, and push code changes.

   1
   git add -A && git commit -m "Upgrade" && git push magento <branch-name>
   

   git add -A is required to add all changed files to source control because of the way Composer marshals base packages. Both composer install and composer update marshal files from the base package (magento/magento2-base and magento/magento2-ee-base) into the package root.

   The files that 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.

4. Wait for deployment to complete.

5. Verify the upgrade in your Integration, Staging, or Production environment by using SSH to log in and check the version.

   1
   php bin/magento --version
   

Create a new config.php file

As mentioned in Configuration management, after upgrading, you need to create an updated config.php file. Complete any additional configuration changes through the Magento Admin in your Integration environment.

To create a system-specific configuration file:

1. From the terminal, use an SSH command to generate the /app/etc/config.php file for the environment.

   1
   ssh <SSH-URL> "<Command>"
   

   For example for Pro, to run the scd-dump on the integration branch:

   1
   ssh <project-id-integration>@ssh.us.magentosite.cloud "php vendor/bin/m2-ece-scd-dump"
   

2. Transfer the config.php file to your local workstations using rsync or scp. You can only add this file to the branch locally.

   1
   rsync <SSH-URL>:app/etc/config.php ./app/etc/config.php
   

3. Add, commit, and push code changes.

   1
   git add app/etc/config.php && git commit -m "Add system-specific configuration" && git push magento master
   

   This generates an updated /app/etc/config.php file 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 edit the file manually.

Upgrading extensions

Review your third-party extension and module pages in Marketplace or other company sites to verify support for Magento Commerce and Magento Commerce Cloud. If you need to upgrade any third-party extensions and modules, we recommend working in a new Integration branch with your extensions disabled.

To verify and upgrade your extensions:

1. Create a new branch on your local workstation.

2. Disable your extensions as needed.

3. When available, download extension upgrades.

4. Install the upgrade as documented by the third-party documentation.

5. Enable and test the extension.

6. Add, commit, and push the code changes to the remote.

7. Push to and test in your Integration environment.

8. 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 also recommend upgrading to the latest version of the Fastly CDN module for Magento 2.

Troubleshoot upgrade

If the upgrade failed, you receive an error message in the browser indicating that you cannot access your storefront or the Magento Admin panel:

1
2
3
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:

1. Using SSH, log in to the remote server and open the ./app/var/report/<error number> file.

2. Examine the logs to determine the source of the issue.

3. Add, commit, and push code changes.

   1
   git add -A && git commit -m "Fixed deployment failure" && git push magento <branch-name>