Complete upgrade prerequisites

It is important to understand what is necessary to run Adobe Commerce or Magento Open Source. You must first review the system requirements for the version you are planning to upgrade to.

After reviewing system requirements, you must complete the following prerequisites before upgrading your system:

  • Update all software
  • Verify that a supported search engine is installed
  • Set the open files limit
  • Verify that cron jobs are running
  • Set DATA_CONVERTER_BATCH_SIZE
  • Verify file system permissions
  • Set the pub/ directory root
  • Install the Composer update plugin

Update all software

The system requirements describe exactly which versions of third-party software have been tested with Adobe Commerce and Magento Open Source releases.

Ensure that you updated all system requirements and dependencies in your environment. See PHP 7.4, PHP 8.0, PHP 8.1, and required PHP settings.

Verify a supported search engine is installed

Adobe Commerce and Magento Open Source require Elasticsearch or OpenSearch to be installed in order to use the software.

If you are upgrading from 2.3.x to 2.4, you must check whether you are using MySQL, Elasticsearch, or a third-party extension as your catalog search engine in your 2.3.x instance. The result determines what you must do before upgrading to 2.4.

If you are upgrading patch releases within the 2.3.x or 2.4.x release lines, if Elasticsearch 7.x is already installed, you can optionally migrate to OpenSearch.

You can use the command line or the Admin to determine your catalog search engine:

  • Enter the bin/magento config:show catalog/search/engine command. The command returns a value of mysql, elasticsearch (which indicates Elasticsearch 2 is configured), elasticsearch5, elasticsearch6, elasticsearch7, or a custom value, indicating you have installed a third-party search engine. A value of elasticsearch7 indicates that either Elasticsearch 7 or OpenSearch is installed.

  • From the Admin, check the value of the Stores > Settings > Configuration > Catalog > Catalog > Catalog Search > Search Engine field.

The following sections describe what actions you must take before upgrading to 2.4.0.

MySQL

As of 2.4, MySQL is no longer a supported catalog search engine. You must install and configure Elasticsearch or OpenSearch before upgrading. Use the following resources to help guide you through this process:

Some third-party catalog search engines run on top of the Adobe Commerce search engine. Contact your vendor to determine whether you must update your extension.

Elasticsearch

You must install and configure either Elasticsearch 7.6 or higher or OpenSearch 1.2 before upgrading to 2.4.0. Adobe no longer supports Elasticsearch 2.x, 5.x, and 6.x.

Refer to Upgrading Elasticsearch for full instructions on backing up your data, detecting potential migration issues, and testing upgrades before deploying to production. Depending on your current version of Elasticsearch, a full cluster restart may or may not be required.

Elasticsearch requires JDK 1.8 or higher. See Install the Java Software Development Kit (JDK) to check which version of JDK is installed.

Configure Magento to use Elasticsearch describes the tasks you must perform after updating Elasticsearch 2 to a supported version.

OpenSearch

OpenSearch is an open source fork of Elasticsearch 7.10.2, following Elasticsearch’s licensing change. The following releases of Adobe Commerce and Magento Open Source introduce support for OpenSearch:

  • 2.4.4
  • 2.4.3-p2
  • 2.3.7-p3

You can migrate from Elasticsearch to OpenSearch only if you are upgrading to a version of Adobe Commerce or Magento Open Source listed above (or higher).

OpenSearch requires JDK 1.8 or higher. See Install the Java Software Development Kit (JDK) to check which version of JDK is installed.

Configure Magento to use Elasticsearch describes the tasks you must perform after changing search engines.

Third-party extensions

We recommend that you contact your search engine vendor to determine whether your extension is fully compatible with 2.4.

Set the open files limit

Setting the open files limit (ulimit) can help avoid failure from multiple recursive calls of long query strings or issues with using the bin/magento setup:rollback command. This command is different for different UNIX shells. Consult your individual flavor for specifics about the ulimit command.

Adobe recommends setting the open files ulimit to a value of 65536 or more, but you can use a larger value if necessary. You can set the ulimit on the command line or you can make it a permanent setting for the user’s shell.

To set the ulimit from the command line:

  1. Switch to the file system owner.

  2. Set the ulimit to 65536.

    ulimit -s 65536
    
    NOTE

    The syntax for open files ulimit depends on the UNIX shell you use. The preceding setting should work with CentOS and Ubuntu with the Bash shell. However, for Mac OS, the correct setting is ulimit -S 65532. Consult a man page or operating system reference for more information.

To set the value in your Bash shell:

  1. Switch to the file system owner.

  2. Open /home/<username>/.bashrc in a text editor.

  3. Add the following line:

    ulimit -s 65536
    
  4. Save your changes to the .bashrc file and exit the text editor.

IMPORTANT

We recommend that you avoid setting a value for the pcre.recursion_limit property in the php.ini file because it can result in incomplete rollbacks with no failure notice.

Verify cron jobs are running

The UNIX task scheduler cron is critical to day-to-day Adobe Commerce and Magento Open Source operations. It schedules things like reindexing, newsletters, e-mails, sitemaps, and so on. Several features require at least one cron job running as the file system owner.

To verify that your cron job is set up properly, check the crontab by entering the following command as the file system owner:

NOTE

The crontab is the configuration file responsible for running cron jobs.

crontab -l

Results similar to the following should display:

#~ MAGENTO START c5f9e5ed71cceaabc4d4fd9b3e827a2b
* * * * * /usr/bin/php /var/www/html/magento2/bin/magento cron:run 2>&1 | grep -v "Ran jobs by schedule" >> /var/www/html/magento2/var/log/magento.cron.log
#~ MAGENTO END c5f9e5ed71cceaabc4d4fd9b3e827a2b

Another symptom of cron not running is the following error in the Admin:

To see the error, click System Messages at the top of the window as follows:

See Configure and run cron for more infromation.

Set DATA_CONVERTER_BATCH_SIZE

Adobe Commerce 2.4 includes security enhancements that require some data to be converted from serialized to JSON. This conversion occurs during the upgrade and it can take a long time, depending on how much data is in your database.

The following tables are affected the most:

  • catalogrule
  • core_config_data
  • magento_reward_history
  • quote_payment
  • quote
  • sales_order_payment
  • sales_order
  • salesrule
  • url_rewrite

If you have a large amount of data, you can improve performance by setting the value of an environment variable, DATA_CONVERTER_BATCH_SIZE. By default, the value is set to 50,000.

To set the environment variable:

  1. Switch to the file system owner.

  2. Set the variable:

    export DATA_CONVERTER_BATCH_SIZE=100000
    
    NOTE

    DATA_CONVERTER_BATCH_SIZE requires memory; avoid setting it to a large value (approximately 1GB) without testing it first.

  3. After your upgrade is complete, you can unset the variable:

    unset DATA_CONVERTER_BATCH_SIZE
    

Verify file system permissions

For security reasons, Adobe Commerce and Magento Open Source require certain permissions on the file system. Permissions are different from ownership. Ownership determines who can perform actions on the file system; permissions determine what the user can do.

Directories in the file system must be writable by the file system owner’s group.

To verify that your file system permissions are set properly, either log in to the application server or use your hosting provider’s file manager application.

For example, enter the following command if the application is installed in /var/www/html/magento2:

ls -l /var/www/html/magento2

Sample output:

total 1028
drwxrwx---. 12 magento_user apache   4096 Jun  7 07:55 .
drwxr-xr-x.  3 root         root     4096 May 11 14:29 ..
drwxrwx---.  4 magento_user apache   4096 Jun  7 07:53 app
drwxrwx---.  2 magento_user apache   4096 Jun  7 07:53 bin
-rw-rw----.  1 magento_user apache 439792 Apr 27 21:23 CHANGELOG.md
-rw-rw----.  1 magento_user apache   3422 Apr 27 21:23 composer.json
-rw-rw----.  1 magento_user apache 425214 Apr 27 21:27 composer.lock
-rw-rw----.  1 magento_user apache   3425 Apr 27 21:23 CONTRIBUTING.md
-rw-rw----.  1 magento_user apache  10011 Apr 27 21:23 CONTRIBUTOR_LICENSE_AGREEMENT.html
-rw-rw----.  1 magento_user apache    631 Apr 27 21:23 COPYING.txt
drwxrwx---.  4 magento_user apache   4096 Jun  7 07:53 dev
-rw-rw----.  1 magento_user apache   2926 Apr 27 21:23 Gruntfile.js
-rw-rw----.  1 magento_user apache   7592 Apr 27 21:23 .htaccess
-rw-rw----.  1 magento_user apache   6419 Apr 27 21:23 .htaccess.sample
drwxrwx---.  4 magento_user apache   4096 Jun  7 07:53 lib
-rw-rw----.  1 magento_user apache  10376 Apr 27 21:23 LICENSE_AFL.txt
-rw-rw----.  1 magento_user apache  30634 Apr 27 21:23 LICENSE_EE.txt
-rw-rw----.  1 magento_user apache  10364 Apr 27 21:23 LICENSE.txt
-rw-rw----.  1 magento_user apache   4108 Apr 27 21:23 nginx.conf.sample
-rw-rw----.  1 magento_user apache   1427 Apr 27 21:23 package.json
-rw-rw----.  1 magento_user apache   1659 Apr 27 21:23 .php_cs
-rw-rw----.  1 magento_user apache    804 Apr 27 21:23 php.ini.sample
drwxrwx---.  2 magento_user apache   4096 Jun  7 07:53 phpserver
drwxrwx---.  6 magento_user apache   4096 Jun  7 07:53 pub
-rw-rw----.  1 magento_user apache   2207 Apr 27 21:23 README_EE.md
drwxrwx---.  7 magento_user apache   4096 Jun  7 07:53 setup
-rw-rw----.  1 magento_user apache   3731 Apr 27 21:23 .travis.yml
drwxrwx---.  7 magento_user apache   4096 Jun  7 07:53 update
drwxrws---. 11 magento_user apache   4096 Jun 13 16:05 var
drwxrws---. 29 magento_user apache   4096 Jun  7 07:53 vendor

See the following for an explanation of the sample output:

  • Most of the files are -rw-rw----, which is 660
  • drwxrwx--- = 770
  • -rw-rw-rw- = 666
  • The file system owner is magento_user

To get more detailed information, you can enter the following command:

ls -la /var/www/html/magento2/pub

Because Adobe Commerce and Magento Open Source deploy static file assets to subdirectories of pub, it’s a good idea to verify permissions and ownership there as well.

For more information, see File system permissions and ownership.

Set the pub/ directory root

See Modify docroot to improve security for more details.

Install the Composer update plugin

The magento/composer-root-update-plugin Composer plugin resolves changes that must be made to the root project composer.json file before updating to a new product requirement.

The plugin partially automates the manual upgrade by identifying and helping you resolve dependency conflicts instead of requiring you to identify and fix them manually.

To install the plugin:

  1. Add the package to your composer.json file.

    composer require magento/composer-root-update-plugin ~2.0 --no-update
    
  2. Update the dependencies:

    composer update
    

On this page