Upgrade Magento version

You can upgrade the core Magento Commerce code base to version 2.1. If you need to upgrade from a version older than 2.1, you must upgrade to a supported version first.

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.

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.

magento-cloud db:dump

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.

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

Change to your Magento root directory and set the upgrade version.

composer require magento/magento-cloud-metapackage <requiredversion> --no-update

Update the project.
```
1
composer update
```
Add, commit, and push code changes.
```
1
git add -A && git commit -m "Upgrade" && 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. Both composer install and composer update marshal files from the base package (that is, magento/magento2-base and 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.
```
1
php bin/magento --version
```

Verify and upgrade your extensions

If you need to upgrade any third-party extensions and modules that support version 2.1, 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.1.

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.1.X.

Troubleshoot upgrade

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 ./app/var/report/<error number> file.
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>

Apr 19th, 2019