By design, the Magento Cloud solution eases the way for upgrading any particular environment. However, some precautions need to be taken in case the upgrading results are not as the owner and/or administrator expected.

Step 1: Check environment health

Before starting any upgrade process, the owner/administrator must check the current status of the environment to be upgraded. This will discard any issue related to the upgrade process.

Step 2: Take snapshot

The easiest way to create a snapshot is by going to the Cloud Interface, then selecting the Master environment and finally clicking on snapshots.

By doing this, the snapshot will save the current state for all environments/branches. Note: depending on the package, besides the Master environment, some other environment might allow taking snapshots.

Another way to take a snapshot is by executing the magento cloud CLI mgc snapshot:create.

$ mgc snapshot:create

Step 3: Database backup 

The fastest way to backup the database is by executing the by executing the magento cloud CLI mgc db:dump, this command will automatically download the database content of the selected environment.

$ mgc db:dump

Although, the upgrading process is very simple; by following these simple recommendations, the upgrading process might have more resources for troubleshooting in case of dealing with unexpected setbacks.

On some rare occasions, after an upgrade; due to compatibility issues between hardware/software components,  when trying to logging you might only see a nasty black screen, or the OS will bring you back to the logins screen; meaning that you are not able to log in at all into Ubuntu.

In most cases, the solution requires direct access to shell and manually make some adjustments. 

Open shell view

You can boot on shell root (no need to login) or press CTRL+ALT+F5 to switch to shell view.

Create a test account for discarding configuration issues.

Creating a temporary account will help to discard any configuration issue in the home directory. The following commands will create a new temporary account for testing purposes:

sudo adduser temporary

sudo systemctl reboot

If you are not able to log in with the new temporary account it means that the issue is within your original account’s home folder; so for this reason, the old configuration files need to be deleted in order to allow a normal login:

rm -rf  ~/.config

rm -rf ~/.local

rm -rf ~/.cache

rm -rf ~/.nvidia-settings-rc

rm ~/.nv

sudo systemctl reboot

If after rebooting the issue persists, please go back to shell view and continue troubleshooting.

Reinstall the login manager

After an upgrade, some core UI related components might be causing a conflict, so it is recommended to reinstall the GNOME Display Manager and the desktop environment by running the following commands:

sudo apt install –reinstall gdm3 ubuntu-desktop gnome-shell

sudo systemctl reboot

If after rebooting the issue persists, please go back to shell view and continue troubleshooting.

Reinstall NVIDIA Driver

A recent NVIDIA update might also be causing the login issues, so for this reason it would need to be reinstalled. To remove the NVIDIA driver, run the following commands:

sudo apt purge ~nnvidia

sudo apt autoremove

sudo apt clean

After the NVIDIA driver has been removed, reinstall it by executing the following commands:

sudo apt update

sudo apt full-upgrade

sudo ubuntu-drivers autoinstall

sudo systemctl reboot

In most cases, after following these steps, Ubuntu should be able to normally log into Ubuntu; if the problem persists you might need to consider to re-install your OS or look more deeply into any hardware issue.

Upgrading the Magento version for any particular environment in Magento Cloud could vary depending on the version to be installed and other running Magento services.

Before the upgrade please check the recommended configuration for the specific Magento version to be installed; by doing this, you would reduce the redeployment time and decrease any risk of unexpected installation errors.

You can check here and here for more information on how to select the correct configuration for your environment.

Upgrading the Magento version is as follows: 

1. By using CLI, change to your local Magento root directory and set the upgrade version using the version constraint syntax:

composer require “magento/magento-cloud-metapackage”:”>=CURRENT_VERSION <NEXT_VERSION” –no-update

For example, when upgrading from version 2.3.7 to version 2.3.8, the execution should as follows:

composer require “magento/magento-cloud-metapackage”:”>=2.3.7 <2.3.8″ –no-update

1. Manually edit the composer.json file for modifying the PHPUnit accordingly with the PHP version, just as indicated in the following table

PHPUnit version	PHP version
9	>= 7.3
8	>= 7.2
7	7.1 ~ 7.4
6	7.0 ~ 7.2

In case you are not performing unit or integration tests you might just delete the entries on the require-dev section and leave all blank:

“require-dev”: {

},

1. For avoiding conflicts with previous packages you might need to remove the composer.lock file for forcing regeneration of this file:

1. Update the project.

composer update –with dependencies

1. Add, commit, and push code changes.

git add -A

git commit -m “Upgrade Magento version”

git push origin <branch-name>

1. Wait for deployment to complete.

1. Verify the upgrade in the environment by using SSH to log in and check the version.

php bin/magento –version

After verifying the Magento version, the environment is ready to be used. Also, do not forget to create backups of your database, code, and media files before upgrading the Magento version in the environment.

Usually, when Ubuntu is installed on a desktop PC, the booting process will go through the GRUB menu, where you can select the OS to boot and/or select a different booting option. However, there are situations that might urge you to use a root shell, such as booting errors, driver installation, hardware configuration, etc.

Supposing that the Ubuntu version is 14.04, or later when the GRUB menu is fully loaded you can select Advanced options for Ubuntu.

After that, a list of available kernels will be available  for booting in Recovery mode 

Then, after pressing on any of the recovery options the screen will display the Recovery Menu, where you can choose Drop to a root shell prompt.

At this point, a terminal will be open, and there is no need to sudo for any task; however, 

if you require writing access to all files,  you must mount the filesystem by executing the following command:

mount -o rw,remount /

After finalizing executing all required activities, you can execute exit for returning to the GRUB menu.

exit

After this, every change made in the root console will be applied immediately in the next booting. 

Happy coding!

Nowadays, installing third-party packages through composer is a very common practice in any project. The code installed by composer is a public version of code from the Internet, which means that it cannot be arbitrarily modified.

In practice, it is inevitable that developers will encounter bugs in third-party packages, where no corrections have been released yet. By design, developers cannot directly modify the code downloaded from composer, because every time the composer is updated and installed the code will be overwritten by the public version again. In response to such correction requirements, Magento Cloud has designed patch mechanisms during and after the deployment process.

To apply a patch, developers need to create a patch file. Supposing that we want to add a line of comment as follows to the file vendor/magento/framework/Phrase.php:

First, create a copy of the file to be modified, in this case: vendor/magento/framework/Phrase-fix.phpvendor/magento/framework/Phrase.php to and copy it in the same root location as follows: vendor/magento/framework/Phrase-fix.phpvendor/magento/framework/Phrase-fix.php.

After modification, the following commands need to be executed in the project root directory as a root:

diff -rupN vendor/magento/framework/Phrase.php vendor/magento/framework/Phrase-fix.php > demo.patch

This command compares the original file Phrase.php with the new file Phrase-fix.php and generates a demo.patch file with the differences between them.

Then, open the demo.patch file for making adjustments:

First, add the git diff information and modify it to the original file change:

diff –git a/vendor/magento/framework/Phrase.php b/vendor/magento/framework/Phrase.php

index 3ee2rd7..8349152 111644

The index is a git hash, but it can be given arbitrarily since vendor files are usually listed in .gitignore.

Adjust the file path as follows:

— A/vendor/magento/framework/Phrase.php 2021-04-14 23:05:30.077087570 +0800

+++ b/vendor/magento/framework/Phrase.php 2021-04-14 23:05:22.469044185 +0800

At the end the adjusted patch file content would like as follows:

After this, the file patch can be placed into the m2-hotfixes folder in the cloud root project, if there is no such folder, it needs to be created.

The last step is to push the changes to the environment. After the deployment is completed, the patch should be applied successfully.

First, check the contents of the target file:

As expected, the changes have been added. In addition, Magento Cloud also provides tools to view the patch status by executing the following command:

php ./vendor/bin/ece-patches status

The patch file just uploaded will appear in the list, and it shows that it has been executed.

Besides this patch, there are many unexecuted patches on the list. These are some optional official patch files released by Magento. They are also easy to apply. For example, for applying MDVA-12304 and MDVA-30972 they need to be added in the .magento.env.yaml file as follows:

stage:

   build:

     QUALITY_PATCHES:

       – MDVA-12304

       – MDVA-30972

Then, commit the changes and push them to the environment for applying them. After redeploying the same command can be executed for confirmation: 

php ./vendor/bin/ece-patches status

After confirmation, the environment can continue working as usual; however, it is recommended to apply patches only if the regular Magento customization options (preferences, plugins, etc) are not convenient for the specific code and/or the 3rd vendor module provider has not provided any code update via composer.