Patch Magento Commerce (Cloud)

You can apply patches to update Magento Commerce (Cloud). We recommend using a new active branch and Integration environment for applying and testing the patch prior to fully deploying across all environments. We strongly recommend you test patches locally so you can identify and resolve any issues.

The composer update command performs a Magento Commerce (Cloud) upgrade with patches and hotfixes. Check the magento/magento-cloud-configuration/patches folder for available patches.

To upgrade and test Magento Commerce (Cloud) (including patches and hotfixes), see Upgrade Magento Commerce (Cloud). Starting with 2.2.0, we use magento/ece-tools to update Magento Commerce (Cloud) with new features and fixes and to update build and deploy processes. See Upgrade to ece-tools to start using magento/ece-tools in 2.1 instead of magento/magento-cloud-configuration.

We recommend installing full Magento Commerce (Cloud) upgrades for important security updates. Full upgrades include all associated patches and hotfixes.

There are two types of patches:

  • General patches

    These patches are provided for all Magento Commerce customers in a GitHub repository that’s referenced in your composer.json. We apply these patches automatically during the build phase.

    To install general patches, use composer update, test your system, and push the patches to the remote server.

  • Custom patches

    Custom patches can be provided by Magento to address a specific issue you raised in a Support ticket. Third-party extension developers can also provide a custom patch.

    Copy custom patches to the m2-hotfixes directory and test them on your locally. After successfully testing them, push the patches to the remote server.

Always apply and test a patch your local system in an active branch. You can push and test in an Integration environment prior to deploying across all environments. All environments are read-only. You must update locally and push the Git branch to deploy across all environments.

Our patches are Composer driven. For more information on Composer, see Composer in Cloud. When you perform a Magento Commerce (Cloud) upgrade, you automatically upgrade with patches and hotfixes through the composer update command.

Verify or set the ADMIN_EMAIL variable

The environment variable ADMIN_EMAIL is required for upgrading and patching. This email is used for sending password reset requests and verified during when updating Magento Commerce (Cloud). See Set environment and project variables.

Back up the database

We recommend that you first back up the database of the system you are upgrading. Use the following steps to back up your Integration, Staging, and Production environments.

Back up your Integration environment database and code:

  1. Enter the following command to make a local backup of the remote database:

    magento-cloud db:dump

  2. Enter the following command to back up code and media:

    php bin/magento setup:backup --code [--media]

    You can optionally omit [--media] if you have a large number of static files that are already in source control.

Back up your Staging or Production environment database before deploying to those environments:

  1. SSH to the server.

  2. Enter the following command to create a database dump:

    vendor/bin/ece-tools db-dump
  • We recommend putting the application in maintenance mode before doing a database dump in Production environments.
  • The command creates an archive in your local project directory called dump-<timestamp>.sql.gz. Refer to Snapshot and backup management for more information.

Verify other changes

Verify other changes you’re going to submit to source control before you start the upgrade:

  1. If you haven’t done so already, change to your project root directory.

  2. Enter the following command:

    git status
  3. If there are changes you do not want to submit to source control, branch or stash them now.

Apply the patch

To apply the patch, you run the composer update command. The command uses composer.json to pull and install the patch to your local. When complete, you will add the files to the Git branch and push to build and deploy.

If multiple patches are installed, they are applied in order by name. The name of the patches include the version number.

  1. Change to your Magento base directory and enter the following command:

    composer update

    This command automatically upgrades for patches associated to the installed Magento Commerce version.

  2. Add, commit, and push your changes to initiate a deployment:

    git add -A
git commit -m "Upgrade patch"
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.

    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.

  3. Wait for deployment to complete.

Test general patches

General patches are provided for all Magento Commerce customers in a repository referenced in your composer.json. We apply patches automatically during the build phase when a patch is available. The procedure discussed in this section enables to you test a patch locally anytime you choose.

Get started

We recommend testing patches in an active branch, prior to deploying to Staging and Production environment.

  1. Log in to your local development system, or switch to, the Magento file system owner.
  2. Change to a directory to which the Magento file system owner has write access.

  3. Enter the following command in a terminal to log in to your project:

    magento-cloud login

  4. List your projects. With the project ID, you can complete additional commands.

    magento-cloud project:list

  5. If necessary, clone the project to your local. You should have cloned when setting up your local development workspace.

    magento-cloud project:get <project ID>
  6. Change to a project directory. For example, cd /var/www/html/magento2

  7. List environments in the project. Every environment includes an active Git branch of your code, database, environment variables, configurations, and services.

    magento-cloud environment:list

    magento-cloud environment:list displays environment hierarchies whereas git branch displays does not. If you have any nested environments, use magento-cloud environment:list to see the full list.

  8. Fetch origin branches to get the latest code:

    git fetch origin

  9. Check out, or switch to, a specific branch and environment. Git commands only checkout the Git branch. The Magento Cloud command also switches to the active environment.

    magento-cloud environment:checkout <environment ID>

    To create a new environment, use magento-cloud environment:branch <environment name> <parent environment ID>

  10. Pull any updated code to your local for the environment ID (which is the Git branch):

    git pull origin <environment ID>

  11. Create a snapshot of the environment as a backup:

    magento-cloud snapshot:create -e <environment ID>

Test a general patch on your local system

To test a general patch on your local system, you create a branch from the Pro Integration master branch or Starter plan staging branch. The commands used in the instructions are for Pro plan using the master branch.

  1. On your local system, enter the following commands as the Magento file system owner:

    cd <project root dir>
magento-cloud environment:checkout master
git pull origin master
composer update

  2. Apply the patch locally:

    git apply vendor/magento/magento-cloud-configuration/patches/<patch file name>

  3. Clean the Magento cache:

    php <Magento project root dir>/bin/magento cache:clean

    You can also clean the cache using the Magento Admin.

  4. Thoroughly test your local system to make sure the patch doesn’t have unexpected side-affects.

  5. After testing the patch, push it to the remote server and deploy it:

    git add -A && git commit -m "Apply patch"
git push origin <branch name>

Patch vendor/magento/ece-tools

This is only required when we release vendor/magento/ece-tools updates.

  1. Open a terminal and create a branch in your local environment.

  2. Enter the following command to patch vendor/magento/ece-tools:

    composer update magento/ece-tools
  3. Push your changes to the remote server: 
    git add composer.lock && git commit -m "Update magento/ece-tools"
git push origin <branch name>

Push a general patch to Staging or Production environments

After you’ve successfully tested a patch locally and on your Integration environment, you can push the patch to Staging or Production environment:

  1. Open an SSH connection to your Staging or Production environment. For Starter, see the Project Web Interface for the SSH links. Your Production environment is the Master. For Pro, the SSH access is one of the following:

    • Staging: ssh -A <project ID>_stg@<project ID>.ent.magento.cloud
    • Production: ssh -A <project ID>@<project ID>.ent.magento.cloud

  2. Enter the following commands:

    <Magento project root dir>/composer update

  3. Apply the patch locally:

    git apply vendor/magento/magento-cloud-configuration/patches/<patch file name>

  4. Clean the Magento cache:

    php <Magento project root dir>/bin/magento cache:clean

    You can also clean the cache using the Magento Admin.

  5. Thoroughly test your local system to make sure the patch doesn’t have unexpected side-affects.

  6. After testing the patch, push it to the remote server and deploy it:

    git add -A && git commit -m "Apply patch"
git push origin master

Test custom patches

Custom patches are provided to specific customers in a Support ticket. Before you continue, make sure the patch file we provided you is available.

Get started

We recommend you test a patch locally in an active branch. After completing testing, you can push the branch to Staging and Production.

  1. Log in to your local development system, or switch to, the Magento file system owner.
  2. Change to a directory to which the Magento file system owner has write access.

  3. Enter the following command in a terminal to log in to your project:

    magento-cloud login

  4. List your projects. With the project ID, you can complete additional commands.

    magento-cloud project:list

  5. If necessary, clone the project to your local. You should have cloned when setting up your local development workspace.

    magento-cloud project:get <project ID>
  6. Change to a project directory. For example, cd /var/www/html/magento2

  7. List environments in the project. Every environment includes an active Git branch of your code, database, environment variables, configurations, and services.

    magento-cloud environment:list

    magento-cloud environment:list displays environment hierarchies whereas git branch displays does not. If you have any nested environments, use magento-cloud environment:list to see the full list.

  8. Fetch origin branches to get the latest code:

    git fetch origin

  9. Check out, or switch to, a specific branch and environment. Git commands only checkout the Git branch. The Magento Cloud command also switches to the active environment.

    magento-cloud environment:checkout <environment ID>

    To create a new environment, use magento-cloud environment:branch <environment name> <parent environment ID>

  10. Pull any updated code to your local for the environment ID (which is the Git branch):

    git pull origin <environment ID>

  11. Create a snapshot of the environment as a backup:

    magento-cloud snapshot:create -e <environment ID>

Test a custom patch on your local system

To test a custom patch on your local system:

  1. On your local system, enter the following command as the Magento file system owner if you haven’t done so already:

    mkdir <Magento project root dir>/m2-hotfixes
  2. Copy the patch file to that directory.

  3. Apply the patch locally:

    cd <Magento project root dir>
magento-cloud environment:checkout master
git pull origin master
git apply <Magento project root dir>/m2-hotfixes/<patch file name>

  4. Clean the Magento cache:

    php <Magento project root dir>/bin/magento cache:clean

    You can also clean the cache using the Magento Admin.

  5. After testing the patch, push it to the remote server and deploy it:

    git add -A && git commit -m "Apply patch"
git push origin <branch name>

Push a custom patch to Staging or Production environments

After you’ve successfully tested a custom patch locally and on your Integration environment, you can push the patch to Staging or Production for Starter and Pro.

  1. Open an SSH connection to your Staging or Production environment. For Starter, see the Project Web Interface for the SSH links. Your Production environment is the Master. For Pro, the SSH access is one of the following:

    • Staging: ssh -A <project ID>_stg@<project ID>.ent.magento.cloud
    • Production: ssh -A <project ID>@<project ID>.ent.magento.cloud

  2. On your staging or production system, enter the following command if you haven’t done so already:

    mkdir <Magento project root dir>/m2-hotfixes

  3. Copy the patch file to that directory.

    We suggest using the following command:

    rsync -azvP <source> <destination>

    Options:

    a archive

    z compress

    v verbose

    P partial progress

    For additional options, see the rsync man page.

  4. Apply the patch:

    git apply <Magento project root dir>/m2-hotfixes/<patch file name>

  5. Clean the Magento cache:

    php <Magento project root dir>/bin/magento cache:clean

    You can also clean the cache using the Magento Admin.

  6. After testing the patch, push it to the remote server and deploy it:

    git add -A && git commit -m "Apply patch"
git push origin <branch name>

Upgrade to ece-tools

  1. Modify the build and deploy hook commands in your magento.app.yaml file.

    hooks:
  # We run build hooks before your application has been packaged.
  build: |
          php ./vendor/bin/m2-ece-build
  # We run deploy hook after your application has been deployed and started.
  deploy: |
          php ./vendor/bin/m2-ece-deploy

  2. Update the metapackage version constraint in the composer.json file. See Update the metapackage.

  3. Run Composer update.

    composer update

  4. Add changes to your local files to the Git staging area.

    git add composer.json composer.lock .magento.app.yaml

  5. Commit your changes.

    git commit -m 'Updating cloud deployment tool'

  6. Push your changes to the remote repository.

    git push
Edit this page on GitHub
Give us feedback

相关主题：

Magento电商 github source