How to upgrade from Magento 2.2.8 to 2.3.1

Magento 2 Video Tutorials Beginner Tutorials
1

Extremely Important Notes

  1. This tutorial assumes that you originally installed your copy of Magento 2.2 using the method laid out in the How to set up a web server for Magento 2.2 tutorial. And are therefore familiar with my methods. If you have not done this, then you should make the following assumptions and changes:
    • My superuser is called craig
    • My Magento user is called magento
    • My Magento root Directory is located in /var/www/html/
    • My OS is Ubuntu
    • My Web Server is Apache
  2. Attempting to follow these steps otherwise will result in unwanted results.
  3. Do not follow these instructions without first running a “Snapshot” Backup of your entire server. A normal backup will not suffice because we will be making changes to the Operating System, which is not covered in a conventional backup.
  4. Watch the entire video at least once before attempting to go through the tutorial. This will allow you to ask any questions in advance and allow you to make preparations.
  5. I have only tested this with 2.2.5 and 2.2.8 but in theory this should work with any version when upgrading from any version of 2.2.

During this video, I’ll be showing you How to upgrade from Magento 2.2 to 2.3. The video will be split into several chapters:

  1. Pre-Installation Tasks
    • Verify Owner and Group
    • Switch to Developer Mode
    • Enable Maintenance Mode
    • Magento Backup
    • Remove Sample Data (if applicable)
    • Verify File and Folder Permissions
  2. Installing PHP 7.2
    • Installing PHP 7.2
    • Disable and Enable PHP 7.2
  3. Update Composer
    • Download the installation script
    • Run the installation script
  4. Post-Installation Tasks
    • Updating .htaccess
    • Manually clear some cached folders
    • Remove the upgrade script
    • Run the Magento Upgrade
    • Enable Magento Cache
    • Disable Maintenance Mode
    • Re-Install Sample Data (if applicable)
  5. Troubleshooting

But before I start, I just want to acknowledge that this tutorial is not for everyone. The topics are aimed at nerds like myself who want full control over their web server and Magento installation. Having said that, the tutorial has actually been designed and written for any skill level to follow.

About this article

This article will help you follow along with the video at your own pace. It will also contain any commands that I use so that you can easily copy and paste them. This means that you won’t have to keep squinting at your screen to see what I’m typing. To make it even easier, each of these steps will also contain a timestamp next to it so that you know exactly at what point in the video I’m using them.

Chapter 1: Pre-Installation Tasks

In Chapter 1 of this video, I’m going to be running through some pre-installation tasks. These tasks will ensure that the remainder of the Chapters will go smoothly.

Right now, I am logged into my server as “craig”. Those of you who are familiar with my tutorials will know that “craig” is a superuser.

The very first thing I’m going to do, is navigate to the Magento root directory. I’ll do that by entering [01:46]:

cd /var/www/html/

1.1 Verify Owner and Group

Next I’m going to use my superuser privileges to ensure that all of the Folder and Files in my Magento root directory have the correct Owner and Group setup. Sometimes I find that these can change depending on who’s been working on the server - So, it’s a good thing to check. I’ll use the following command to do this [02:16]:

sudo chown -R magento:www-data .

As this is the first time that I’ve ran a “sudo” since logging in, I’ll be prompted for my password.

And for the time being I’m done as the superuser. So now I’m going to switch to the “magento” user by entering [02:42]:

su magento

Followed by the “magento” users’ password.

1.2 Switch to Developer Mode

The recommended mode to complete an upgrade in is Developer Mode. Because if you run into any issues, then this mode makes things a little easier to debug. So, I’ll trigger Developer Mode by entering [03:00]:

bin/magento deploy:mode:set developer

1.2 Enable Maintenance Mode

The next thing I will do is enable Maintenance Mode because I don’t want anyone trying to use the website whilst I’m running any maintenance tasks. To enable Maintenance Mode, enter [03:20]:

bin/magento maintenance:enable

1.3 Magento Backup

Next I’m going to run a full Magento backup. To run a full Magento backup, I’ll run [03:28]:

bin/magento setup:backup --code --media --db

This will backup my System Code, Media Files and Database.

Technically, there isn’t a need for me to do this because I’ve already created a full “snapshot” of my server before starting this tutorial… However, running a full Magento backup is still a good habit to have. If your Web Host provides you with the ability “snapshot”, I suggest you do that too.

1.4 Remove Sample Data (if applicable)

Before running an upgrade, Magento recommend that you remove all Sample Data first. So, I’ll do that now by entering [04:18]:

bin/magento sampledata:remove

I’ll reinstall the Sample Data towards the end of the video. Obviously, you can skip this step if it doesn’t apply to you.

1.5 Verify File and Folder Permissions

The final Pre-Installation Task is to validate that all of the Files and Folders within the Magento root directory have the correct Permissions. This is something that can also change over time depending on what work your doing in Magento. I’ll do that by running the following set of commands that I’ve strung together into a single line [04:50]:

find var generated vendor pub/static pub/media app/etc -type f -exec chmod g+w {} + && find var generated vendor pub/static pub/media app/etc -type d -exec chmod 775 {} + && chmod u+x bin/magento
digitalstartup-signup

Chapter 2: Installing PHP 7.2

In Chapter 2, I’m going to Prepare, Install and Activate PHP 7.2. Version 7.2 is a requirement of Magento 2.3 as it won’t run on earlier versions.

In order to work on this, I’ll need to switch back to the “craig” user because I’ll need superuser privileges. As I’m already logged in as “craig” but currently switched to the “magento” user, I can just type [05:22]:

exit

As you can see from the Command Line, it now displays “craig”.

2.1 Installing PHP 7.2

I’ll start first by updating the server repositories. This tells Ubuntu what is available to download when I ask it to install something. Kind of like enabling your mobile phone to access the App Store.

Luckily, my server comes with many repositories built-in. So, I only need to add one. This will allow me to download PHP 7.2 and any required modules. I’ll do this by entering [05:56]:

sudo add-apt-repository ppa:ondrej/php

And then I’ll just press the Enter key to continue.

Now I need to tell Ubuntu to update it’s records from all of the connected repositories, including the one I just added. This is done by typing [06:14]:

sudo apt-get update

Now that the preparations have been made, I can now install PHP 7.2 with all of the required modules that Magento 2.3 needs in order to run correctly. I’ve compiled these into a single command [06:34]:

sudo apt-get install php7.2 libapache2-mod-php7.2 php7.2-mysql php7.2-soap php7.2-bcmath php7.2-xml php7.2-mbstring php7.2-gd php7.2-common php7.2-cli php7.2-curl php7.2-intl php7.2-zip zip unzip -y

2.2 Disable and Enable PHP 7.2

With PHP 7.2 and it’s modules now installed, I can go ahead and disable PHP 7.0 (which is the version I’m currently running) by typing [06:55]:

sudo a2dismod php7.0

And then enable PHP 7.2 to typing [07:04]:

sudo a2enmod php7.2

Now, to finally lock in all of these PHP changes I just need to restart Apache with [07:18]:

sudo service apache2 restart

At this stage if I attempted to load Magento in a web browser I would only see an error. This is because Magento 2.2 isn’t compatible with PHP 7.2 - But Magento 2.3 won’t run without it. So, I’m currently in a state of limbo until I upgrade Magento.

Chapter 3: Update Composer

In Chapter 3 I’m going to go through the bulk of the Upgrade Preparations. This will mostly involve preparing and updating the Composer files.

To start, I’ll need to switch back at the “magento” user. If you remember, this is done by entering [07:56]:

su magento

Followed by the password of the “magento” user.

3.1 Download the installation script

This next part normally consists of several steps. But thankfully there is a script that I can download that will automate many of those tasks for me.

The following command will download this script so that I can run it [08:20]:

wget https://raw.githubusercontent.com/magento/magento2/2.3.0/dev/tools/UpgradeScripts/pre_composer_update_2.3.php

That file is now sitting in the location where I ran the command, which is in my Magento root directory.

3.2 Run the installation script

Now, I can run this installation by entering the following command [08:32]:

php -f pre_composer_update_2.3.php -- --root='/var/www/html' --repo=https://repo.magento.com/

This script will seek out the latest 2.3 version. At the time of this video, 2.3.1 is the latest, so that will be what gets prepared by the script. If 2.3.2 were out, then that would be what is prepared instead.

Now that the script has made the appropriate modifications, I’ll need to run a composer update by typing [09:02]

composer update

This process will take around 1-2 minutes.

digitalstartup-signup

Chapter 4: Post-Installation Tasks

In Chapter 4, the Magento 2.3.1 upgrade is ready to be initiated. I’ve validated my files, upgraded PHP and updated Composer. But before I can do that, I should do a little housekeeping to ensure everything goes smoothly.

4.1 Updating .htaccess

After a significant Magento Composer Update is completed, the .htaccess file in the Magento root directory gets overwritten with a default out-the-box copy. This copy sets the PHP memory_limit to 756M. When I originally installed Magento, one of the steps to make Magento work correctly was to change this from 756M to 2G.

First open the .htaccess file [10:14]:

nano .htaccess

Using the Arrow or Page Up/Down keys I’ll work my way down the file and find a line containing memory_limit. There are in fact 2 instances in the file, one under PHP 5 and one under PHP 7. I’ll just go ahead and change the instance under PHP 7.

Replace 756MB with 2G

After, I’ll save my changes, press Ctrl + X.

Then I’ll be asked if you want to save my changes. Simply Type Y and then Enter to do so.

4.2 Manually clear some cached folders

Magento automatically clears many files and folders. However, there are 3 that should be removed manually by deleting the appropriate folders. This is done by entering [11:04]:

rm -rf var/cache/* var/page_cache/* generated/code/*

Important Notes:

  1. On a couple of occasions, I’ve been presented with an error message. Simply entering the command a second time seems to fix it.
  2. If you use a cache storage other than the filesystem, such as Redis or Memcached, you must manually clear the cache there too.

4.3 Remove the upgrade script

Earlier, I downloaded the script to help with the Composer Update. There’s no need to keep that file anymore. So delete the file by entering [11:38]:

rm pre_composer_update_2.3.php

4.4 Run the Magento Upgrade

After all this hard work, it’s time to trigger the Magento Upgrade command that will now process all of the changes I’ve made so far. Do this by typing [11:54]:

bin/magento setup:upgrade

And that’s Magento 2.3.1 now installed.

4.5 Re-Install Sample Data (if applicable)

If at the beginning of the video, you removed the Sample Data from Magento then you can now reinstall it.

Magento has a really useful command for installing all of the sample data from the Magento Repository via Composer. This step can normally take a couple of minutes to complete. At times, it may appear that nothing is happening, but just give it time.

Reinstall the same data by entering [12:38]:

bin/magento sampledata:deploy

I’ve skipped forward a couple of minutes and now the Command Line Interface is awaiting my next command. All I need to tell Magento to do now is install the latest changes I’ve just made by running [12:50]:

bin/magento setup:upgrade

4.6 Enable Magento Cache

After an upgrade, I’ve found that Magento’s Cache will sometimes be disabled which leads to painfully slow load times. So, running the following command will ensure that all of the Caching is enabled [13:10]:

bin/magento cache:enable

The initial loads times will still be slow the first time you load some of the pages, but that loading time will start to reduce significantly.

4.7 Disable Maintenance Mode

And the final step if you wish to do this now, is to disable Maintenance Mode and open the site back up to the public [13:48]:

bin/magento maintenance:disable

To check my work, I’ll load the Frontend of the website… This may take a moment.

And then I’ll log into the backend… And as you can see the latest version of 2.3.1 is displayed in the bottom-right corner.

My last check is to ensure that the Web Setup Wizard can pass the Readiness Check. So, I’m going to attempt to install a 3rd party module to check the results…

And as you can see, everything passes.

Troubleshooting

Whilst putting this tutorial together I kept running into 2 specific issues - Until I eventually worked them out. I’ve listed both of these issues along with a fix below. I did not run into any other issues.

digitalstartup-signup

Final words

Thank you for sticking with the tutorial. I truly hope this video gave you the knowledge and the confidence to try this out for yourself. Don’t forget to like and subscribe if you found this video useful. And don’t forget to come visit the forum to share your experience, ask for help or even offer it. And until next time, take care.