Skip to content

Latest commit

 

History

History
239 lines (154 loc) · 11.1 KB

UPGRADE.md

File metadata and controls

239 lines (154 loc) · 11.1 KB

UPGRADE FROM 3.1 TO 3.2

Use this documentation to migrate projects based on the Community Edition.

Disclaimer

When starting your upgrade, make sure:

  • you created your project from the standard distribution.
  • you performed a backup of your database before proceeding to the migration. You can use tools like mysqldump.
  • you performed a backup of your indices before proceeding to the migration. You can use Elastisearch API _snapshot.
  • you performed a backup of your codebase if you don't use a VCS (Version Control System).

Requirements

Make sure that you're using Akeneo PIM v3.1. You can check this information at the bottom of the dashboard.

Please, see the complete list of requirements for PIM v3.2.

Please provide a server with the following requirements before proceeding to the PIM 3.2 migration. To install those requirements, you can follow the official documentations or our installation documentation on Debian 9 or Ubuntu 16.04.

Migrate your standard project

  1. Stop the job queue consumer daemon consumer

    Before starting the migration process, stop the job queue consumer daemon and start it again only when the migration process is finished.

    If you use supervisor, then stop your daemon as following:

    supervisorctl status
# the command returns the following daemons
# pim-queue-daemon:pim-queue-daemon_00 RUNNING    pid 4162, uptime 0:05:44

supervisorctl stop pim-queue-daemon:pim-queue-daemon_00

supervisorctl status
# the daemon has been stopped
# pim-queue-daemon:pim-queue-daemon_00 STOPPED    Jan 24 11:41 AM

    Otherwise, kill your daemon:

    pkill -f job-queue-consumer-daemon

    To give you a quick overview of the changes made to a standard project, you can check on Github.

    The $PIM_DIR variable will contain the path to your current PIM installation:

    export PIM_DIR=/path/to/your/current/pim/installation

  2. Download the latest standard edition from the website PIM community standard and extract:

    wget http://download.akeneo.com/pim-community-standard-v3.2-latest.tar.gz
tar -zxf pim-community-standard-v3.2-latest.tar.gz
cd pim-community-standard/

  3. Update the configuration files:

    We will copy the configuration file from the new standard edition version. You shouldn't have made a single change to them in your project, but if you did, don't forget to reapply your own changes to the files.

    Then apply the changes, from the standard edition directory:

    cp docker-compose.yml $PIM/docker-composer.yml

    The only change is the addition of a new container object-storage, based on minio (see https://min.io/), and compatible with the Amazon S3 protocol. This container allows testing object storage configuration for assets and media.

  4. Update your app/config/config.yml

    The app/config/config.yml file didn't change between 3.1 and 3.2.

  5. Update your app/config/config_dev.yml and app/config/config_prod.yml

    The app/config/config.yml_dev.yml and app/config/config_prod.yml files didn't change between 3.1 and 3.2.

  6. Update your app/config/config_behat.yml and app/config/config_test.yml:

    The app/config/config.yml_behat.yml and app/config/config_test.yml files didn't change between 3.1 and 3.2.

  7. Update your app/AppKernel.php:

    The app/AppKernel.php file didn't change between 3.1 and 3.2.

  8. Deactivate your custom code

Before updating the dependencies and migrating your data, please deactivate all your custom bundles and configuration. This will considerably ease the migration of your data. You can disable your custom code by commenting out your custom bundles in your AppKernel.php file.

  1. Update your PHP dependencies

    From the downloaded archive:

    cp composer.json $PIM_DIR/
# then add your own dependencies

    The following PHP dependencies have changed:

    • symfony/symfony upgraded to 3.4.28
    • twig/twig upgraded to 1.42.2
    • league/flysystem-aws-s3-v3 1.0 added

    Now we are ready to update the backend dependencies:

    cd $PIM_DIR
php -d memory_limit=3G composer update

    This step will copy the upgrades folder from pim-community-dev/ to your Pim project root in order to migrate. If you have custom code in your project, this step may raise errors in the "post-script" command. In this case, go to the chapter "Migrate your custom code" before running the database migration.

  2. Update your JS dependencies

From the downloaded archive:

```bash
cp package.json $PIM_DIR/
# then add your own dependencies
```

The following PHP dependencies have changed:
  - `cucumber-html-reporter` upgraded to 5.0.0
  - `eslint` upgraded to 6.0.1
  - `jquery` upgraded to 3.4.0
  - `lodash` upgraded to 4.17.14
  1. Migrate your MySQL database

Please, make sure the folder upgrades/schema/ does not contain former migration files (from PIM 2.2 to 2.3 for instance), otherwise the migration command will surely not work properly.

```bash
rm -rf var/cache
bin/console doctrine:migration:migrate --env=prod
```

  1. Migrate your Elasticsearch indices

    In case you updated the settings of Elasticsearch (like normalizers, filters and analyzers), please make sure you properly loaded your custom settings in the Elasticsearch configuration.

    Same in case you have a big catalog and increased the index.mapping.total_fields.limit. Make sure you properly loaded your custom settings in the Elasticsearch configuration.

    As of PIM v3.2, we now take advantage of Elasticsearch's aliases. Thus, all indices have to be reindexed.

    Also, as Elasticsearch does not take into account case insensitivity of option codes when searching and as we modified the way products values are loaded from MySQL, Elasticsearch search has to be case insensitive when searching on option codes. Thus, all mappings have to updated.

    To take into account those two changes:

    php bin/console akeneo:elasticsearch:update-mapping -e prod --all

Migrate your custom code

  1. Apply the sed commands

    Several classes and services have been moved or renamed. The following commands help to migrate references to them:

    find ./src/ -type f -print0 | xargs -0 sed -i 's#Akeneo\\Pim\\Enrichment\\Bundle\\Elasticsearch\\Filter\\Field\\AncestorFilter#Akeneo\\Pim\\Enrichment\\Bundle\\Elasticsearch\\Filter\\Field\\AncestorIdFilter#g'
find ./src/ -type f -print0 | xargs -0 sed -i 's#Akeneo\\Pim\\Enrichment\\Component\\Product\\Factory\\ValueCollectionFactory#Akeneo\\Pim\\Enrichment\\Component\\Product\\Factory\\WriteValueCollectionFactory#g'
find ./src/ -type f -print0 | xargs -0 sed -i 's#Akeneo\\Pim\\Enrichment\\Component\\Product\\Model\\ValueCollection#Akeneo\\Pim\\Enrichment\\Component\\Product\\Model\\WriteValueCollection#g'
find ./src/ -type f -print0 | xargs -0 sed -i 's#Akeneo\\Pim\\Enrichment\\Bundle\\Storage\\ORM\\Connector\\GetConnectorProductModels#Akeneo\\Pim\\Enrichment\\Bundle\\Storage\\Sql\\Connector\\SqlGetConnectorProductModels#g'
find ./src/ -type f -print0 | xargs -0 sed -i 's#ValueCollectionIn\\Pim\\Enrichment\\Bundle\\Storage\\ORM\\Connector\\GetConnectorProductModels#Akeneo\\Pim\\Enrichment\\Bundle\\Storage\\Sql\\Connector\\SqlGetConnectorProductModels#g'
please apply `sed 's/ValueCollectionInterface/WriteValueCollection/g` (it also rename the ValueCollection)

  2. Adapt your custom codes to handle this breaking changes we introduced:

  • Service pim_catalog.saver.channel class has been changed to Akeneo\Channel\Bundle\Storage\Orm\ChannelSaver.

  • Interface Akeneo\Channel\Component\Model\ChannelInterface has a new methods `popEvents(): array

  • The following classes have been removed:

    • Akeneo\Pim\Enrichment\Bundle\EventSubscriber\RemoveUserSubscriber This subscriber has been replaced by a proper Doctrine mapping that set the user at null in the Comment entity for which the user is the author when the user is removed. If you override this service, you can use the same events (StorageEvents::PRE_REMOVE and StorageEvents::POST_REMOVE) on Akeneo\UserManagement\Component\Model\UserInterfaceto fire your own subscriber.

    • Akeneo\Pim\Enrichment\Bundle\Storage\ORM\Connector\GetConnectorProductsFromWriteModel

    • Akeneo\Pim\Enrichment\Bundle\Storage\ORM\Connector\GetMetadataForProductModel

    • Akeneo\Pim\Enrichment\Component\Product\Query\GetMetadata

    • Akeneo\Pim\Enrichment\Component\Product\ProductModel\Query\GetMetadataInterface

    • Akeneo\Pim\Enrichment\Component\Product\Query\GetMetadataInterface These class and interface have been removed from the refactoring of the Akeneo\Pim\Enrichment\Bundle\Storage\ORM\Connector\GetConnectorProductModels. You can check the new class Akeneo\Pim\Enrichment\Bundle\Storage\Sql\Connector\SqlGetConnectorProductModels to see how it has been replaced.

    • Akeneo\Pim\Enrichment\Component\Product\Factory\ValueCollectionFactoryInterface

    • Akeneo\Pim\Enrichment\Component\Product\Model\ValueCollectionInterface These interfaces have been removed. You can now directly extends Akeneo\Pim\Enrichment\Component\Product\Factory\WriteValueCollectionFactory and Akeneo\Pim\Enrichment\Component\Product\Model\WriteValueCollection

  1. Reactivate your custom code

You are now ready to reactivate your custom bundles in the AppKernel.php file.

  1. Then re-generate the PIM assets:
    bin/console cache:clear --env=prod
    bin/console pim:installer:assets --clean --env=prod
    yarn run less
    yarn run webpack
  1. Restart the queue consumer

Now you are ready to restart the queue consumer daemon.

If you use supervisor, then restart your daemon as following:

    supervisorctl status
    # the command returns the following daemons
    # pim-queue-daemon:pim-queue-daemon_00 STOPPED    Jan 24 11:41 AM

    supervisorctl start pim-queue-daemon:pim-queue-daemon_00

    supervisorctl status
    # pim-queue-daemon:pim-queue-daemon_00 RUNNING    pid 3500, uptime 0:00:04
    # the daemon has been restarted