Upgrading Magento Cloud is very simple but it will require you to read a lot of documentation for understanding the correct action plan; so for this reason this article aims to facilitate information on the upgrading procedure in order to help you in making a decision whether your environment needs to upgraded or not.  

Step 1: DB backup: 

Be sure to create all the necessary backups in order to easily roll back the environment in case the upgrading somehow failed or some data is missing after the upgrade.

Step 2: Upgrade Magento Services: 

Update the services that interact between them in the environment. Before upgrade please check the correct services version configuration for your environment.

Step 3: Upgrade the PHP version: 

Update the PHP version installed in the environment through docker. Before upgrade please check the correct version according to the version of the services to be installed or that are already running in your environment.

Step 4: Upgrade the Magento version: 

Update the Magento version installed in the environment through docker. Before upgrade please check the correct version according to the version of the services to be installed or that are already running in your environment.

Step 5: Apply patches (If needed): 

Create all the necessary patches or just apply the patches provided by Magento (just in case it is necessary for your environment.

Please remember that this is a general guide for upgrading your Magento Cloud environment; however, there might be some specific situations that might require specific modifications; but this document might give you a good starting point.

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!