Complete upgrade prerequisites

Last update: Mon Feb 12 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Topics:
Upgrade

CREATED FOR:

Experienced
Admin
Developer

It is important to understand what is necessary to run Adobe Commerce. 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
Convert database table format
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 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.

NOTE

For Adobe Commerce on cloud infrastructure Pro projects, you must create a Support ticket to install or update services in Staging and Production environments. Indicate the service changes needed and include your updated .magento.app.yaml and services.yaml files and PHP version in the ticket. It can take up to 48 hours for the Cloud infrastructure team to update your project. See Supported software and services.

Verify that a supported search engine is installed

Adobe Commerce requires 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. For versions earlier than 2.4.6, use the elasticsearch7 value for the Elasticsearch 7 or OpenSearch engine. For version 2.4.6 and later, use the opensearch value for the OpenSearch engine.
From the Admin, check the value of the Stores > Settings > Configuration > Catalog > Catalog > Catalog Search > Search Engine field.

The following sections describe what actions that 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:

Install and configure Elasticsearch
Installing Elasticsearch
Configure nginx or Apache to work with your search engine
Configure Commerce to use Elasticsearch and reindex

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.

MariaDB

Reindexing on MariaDB 10.4 and 10.6 takes more time compared to previous MariaDB or MySQL versions. To speed up reindexing, we recommend setting these MariaDB configuration parameters:

If you experience performance degradation not related to indexation after upgrading to MariaDB 10.6, consider enabling the --query-cache-type setting. For example, --query-cache-type=ON.

Before upgrading Adobe Commerce on cloud infrastructure projects, you may also need to upgrade MariaDB (see MariaDB upgrade best practices).

For example:

Adobe Commerce 2.4.6 with MariaDB version 10.5.1 or higher
Adobe Commerce 2.3.5 with MariaDB version 10.3 or earlier

In addition to these recommendations, you should consult with your database administrator on configuring the following parameters:

NOTE

These settings are available for on-premises deployments only. Adobe Commerce on cloud infrastructure customers do not have access to these settings.

Search engine

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. Search engine configuration in the Configuration Guide describes the tasks you must perform after upgrading Elasticsearch to a supported version.

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 Java Development Kit (JDK) 1.8 or higher. See Install the Java Software Development Kit (JDK) to check which version of JDK is installed.

OpenSearch

OpenSearch is an open-source fork of Elasticsearch 7.10.2, following Elasticsearch’s licensing change. The following releases of Adobe Commerce introduces support for OpenSearch:

2.4.6 (OpenSearch has a separate module and settings)
2.4.5
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 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.

Search engine configuration describes the tasks you must perform after changing search engines.

Upgrade Elasticsearch

Support for Elasticsearch 8.x was introduced in Adobe Commerce 2.4.6. The following instructions show an example of upgrading Elasticsearch from 7.x to 8.x:

Upgrade the Elasticsearch 7.x server to 8.x and make sure that is is up and running. See the Elasticsearch documentation.

Enable the id_field_data field by adding the following configuration to your elasticsearch.yml file and restarting the Elasticsearch 8.x service.

code language-yaml
`indices: id_field_data: enabled: true`

note info
INFO
To support Elasticsearch 8.x, Adobe Commerce 2.4.6 disallows the `indices.id_field_data` property by default and uses the `_id` field in the `docvalue_fields` property.

In the root directory of your Adobe Commerce project, update your Composer dependencies to remove the Magento_Elasticsearch7 module and install the Magento_Elasticsearch8 module.

code language-bash
`composer require magento/module-elasticsearch-8 --update-with-all-dependencies`

Update your project components.

code language-bash
`bin/magento setup:upgrade`

Configure Elasticsearch in the Admin.

Reindex the catalog index.

code language-bash
`bin/magento indexer:reindex catalogsearch_fulltext`

Delete all items from the enabled cache types.

code language-bash
`bin/magento cache:clean`

Downgrade Elasticsearch

If you inadvertently upgrade the version of Elasticsearch on your server or determine that you need to downgrade for any other reason, you must also update your Adobe Commerce project dependencies. For example, to downgrade from Elasticsearch 8.x to 7.x

Downgrade the Elasticsearch 8.x server to 7.x and make sure that is is up and running. See the Elasticsearch documentation.

In the root directory of your Adobe Commerce project, update your Composer dependencies to remove the Magento_Elasticsearch8 module and its Composer dependencies and install the Magento_Elasticsearch7 module.

code language-bash
`composer remove magento/module-elasticsearch-8`

Update your project components.

code language-bash
`bin/magento setup:upgrade`

Configure Elasticsearch in the Admin.

Reindex the catalog index.

code language-bash
`bin/magento indexer:reindex catalogsearch_fulltext`

Delete all items from the enabled cache types.

code language-bash
`bin/magento cache:clean`

Third-party extensions

We recommend that you contact your search engine vendor to determine whether your extension is fully compatible with an Adobe Commerce release.

Convert database table format

You must convert the format of all database tables from COMPACT to DYNAMIC. You must also convert the storage engine type from MyISAM to InnoDB. See best practices.

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:

Switch to the file system owner.

Set the ulimit to 65536.

code language-bash
`ulimit -n 65536`

To set the value in your Bash shell:

Switch to the file system owner.
Open /home/<username>/.bashrc in a text editor.

Add the following line:

code language-bash
`ulimit -n 65536`

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 that cron jobs are running

The UNIX task scheduler cron is critical to day-to-day Adobe Commerce operations. It schedules things like reindexing, newsletters, e-mails, and sitemaps. 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 information.

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:

Switch to the file system owner.

Set the variable:

code language-bash
`export DATA_CONVERTER_BATCH_SIZE=100000`

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

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

code language-bash
`unset DATA_CONVERTER_BATCH_SIZE`

Verify file system permissions

For security reasons, Adobe Commerce requires 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 into 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 deploys 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:

Add the package to your composer.json file.

code language-bash
`composer require magento/composer-root-update-plugin ~2.0 --no-update`

Update the dependencies:

code language-bash
`composer update`

recommendation-more-help

83a60e0e-8849-4685-a8cd-c129ecd795ea

Complete upgrade prerequisites

Update all software

Verify that a supported search engine is installed

MySQL

MariaDB

Search engine

OpenSearch

Upgrade Elasticsearch

Downgrade Elasticsearch

Third-party extensions

Convert database table format

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

Set the `pub/` directory root