Upgrade from 5.0 to 6.0¶

Use this documentation to upgrade projects based on Akeneo PIM Community Edition or Enterprise Edition 5.0 to 6.0.

Disclaimer¶

Warning

Make sure your production database is backed-up and the queue daemon(s) have been stopped before performing any data migration.

Prepare your project for the new technical stack¶

Note

Your 5.0 application must be on the latest patch and migrations must be up-to-date before migrating to the new technical stack.

If you do not apply the most recent patch and migrations, you may experience problems upgrading.

Check the most recent patch version here:

You can check your current patch version with the following command: composer licenses | grep akeneo/pim

To install the most recent patch, use the instructions in How to apply a patch?

The directory at the root of your current installation is referred to as $INSTALLATION_DIR.

Warning

Please note that this part of the migration needs to be executed on your PIM 5.0 before upgrading your technical stack.

$ export APP_ENV=prod
$ cd $INSTALLATION_DIR
$ cp -R ./vendor/akeneo/pim-community-dev/upgrades/* ./upgrades/
$ cp -R ./vendor/akeneo/pim-enterprise-dev/upgrades/* ./upgrades/
$ php bin/console doctrine:migrations:migrate
$ rm -rf var/cache/

If you are updating an Enterprise Edition instance and are working with Akeneo Support, please run the following command (after executing doctrine:migrations:migrate) and provide us with the output so that we can quickly check for any database issues:

$ php bin/console doctrine:migration:status

Requirements¶

Updated System components¶

Note

If you are using Enterprise Edition on the Akeneo Cloud Flexibility offering, Akeneo will handle the component upgrades if you open a ticket with our Support team.

Your system components must be updated to the versions required for Akeneo PIM:

PHP 8.0
MySQL 8.0
Elasticsearch 7.16

Note

Elasticsearch supports in-place update.

Elasticsearch 7.16 will be able to use indexes created by previous versions of Elasticsearch 7.x.

This means there’s no need to export and reimport data for this update.

Updated System dependencies¶

Check your system dependencies are in sync with the System Requirements

Updated crontab definition¶

Check that your crontab is in sync with Periodic tasks & Crontab configuration

Upgraded Virtual Host configuration¶

OnPremise only¶

Akeneo PIM uses one fpm pool each for the API and the UI.

You can check the VirtualHost configuration for 6.0 on your system: Install Akeneo PIM manually

Prepare your project¶

Akeneo PIM composer.json¶

Community Edition¶

You can download the composer.json file directly from the Github repository:

$  curl https://raw.githubusercontent.com/akeneo/pim-community-standard/6.0/composer.json > $INSTALLATION_DIR/composer.json

Enterprise Edition¶

Please visit your Akeneo Portal to download the archive, then expand it to the installation directory on your host:

$ tar xvzf pim-enterprise-standard-<ARCHIVE-SUFFIX>.tar.gz -C $INSTALLATION_DIR --strip-components 1 pim-enterprise-standard/composer.json

Load your PIM Enterprise dependencies¶

$ composer update

Note

You may need to temporarily increase the memory provided to composer, as this step can be very memory consuming:

$ php  -d memory_limit=4G <COMPOSER PATH>/composer update

Let Akeneo PIM continue the preparation for you¶

Warning

Do not skip this step

This script overwrites several configuration files, but it is necessary for the upgrade to succeed.

If you have customized your PIM (for example, by adding custom bundles), we suggest saving a backup copy of your configuration files, and you will need to resolve any conflicts.

Community Edition¶

$ export APP_ENV=prod
$ vendor/akeneo/pim-community-dev/std-build/migration/prepare_50_to_60.sh

Enterprise Edition¶

$ export APP_ENV=prod
$ vendor/akeneo/pim-enterprise-dev/std-build/upgrade/prepare_50_to_60.sh

Make sure your environment is ready to be migrated¶

$ rm -Rf var/cache
$ bin/console pim:installer:check-requirements

If this command detects something not working or not properly configured, please fix the problem before continuing.

Prepare the front-end¶

$ make upgrade-front

Migrate your data¶

$ bin/console doctrine:migrations:migrate
$ bin/console pimee:data-quality-insights:migrate-product-criterion-evaluation
$ bin/console pim:data-quality-insights:recompute-product-scores

Note

You may receive the following warning:

WARNING! You have [a number of] previously executed migrations in the database that are not registered migrations.

This can be safely ignored. The message means that your database is up to date, but that Doctrine did not find the migration files corresponding to some prviously-run migrations.

Note

You may also receive:

Migration _X_Y_ZZZZ was executed but did not result in any SQL statements

If a migration only affects the Elasticsearch index or does not apply because no data associated with the migration were found, this can be safely ignored.

Note

The following message can also be safely ignored if it concerns the data-quality-insights migration:

The migration has already been performed.

Migrate the job queue¶

In 6.0 we set up a new job queue (also known as job consumers). If you have jobs awaiting execution in the old queue, they must be migrated to the new queue.

$ bin/console akeneo:batch:migrate-job-messages-from-old-queue

(Use the --no-interaction flag if you want to skip the interactive question and want to migrate directly.)

Migrating your custom code¶

Note

Each Akeneo PIM version brings brand new features, so please check if you still need each custom bundle, as we may have incorporated the same or similar functionality into the PIM.

You can check for new features and changes in the changelog: Where is the Changelog?

Applying automatic fixes¶

Some changes we made in the code of Akeneo PIM can be automatically applied to your own code.

In order to make this process easier and more error proof, we decided to use PHP Rector. to apply these changes.

Installing Rector¶

composer require --dev rector/rector-prefixed

Applying automatic fixes¶

vendor/bin/rector process src/

Note

This will use the rector.yaml file created by the prepare.sh above. Feel free to add your own refactoring rules inside it. More information on getrector.org.

Identifying broken code¶

You can use PHPStan to help you identify broken code:

composer require --dev phpstan/phpstan
vendor/bin/phpstan analyse src/

For more information, please check the PhpStan documentation.

You should migrate your bundles one by one to avoid problems and locate any bugs.

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!