Important

You are browsing the documentation for version 4.2 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Upgrade

This guide explains how to upgrade OroCommerce, OroCRM or OroPlatform application to the next version.

An absolute path to the directory where an application is installed will be used in the guide and will be referred to as <application-root-folder> further in this topic.

Note

We highly recommend running all the commands in this guide from the same user the web server runs (e.g., nginx or www-data).

1. Checkout from the GitHub Repository

To retrieve a new version and upgrade your Oro application instance, execute the following steps:

1. Make sure that there are no changes that require the database schema update.

   php bin/console oro:entity-extend:update --dry-run --env=prod
   

   The platform update is possible only when the database schema is up-to-date.

2. Go to the Oro application root folder and switch the application to the maintenance mode.

   cd <application-root-folder>
   php bin/console lexik:maintenance:lock --env=prod
   

3. Stop the cron tasks.

   crontab -e
   

   Comment this line .

   */1 * * * * /usr/bin/php <application-root-folder>/bin/console --env=prod oro:cron >> /dev/null
   

4. Stop all running consumers.

5. Create backups of your Database and Code.

6. Pull changes from the repository.

   Note

   If you have any customization or third party extensions installed, make sure that:

   • your changes to src/AppKernel.php file are merged to the new file.

   • your changes to src/ folder are merged and it contains the custom files.

   • your changes to composer.json file are merged to the new file.

   • your changes to configuration files in config/ folder are merged to the new files.

   git pull
   git checkout <VERSION TO UPGRADE>
   

7. Upgrade the composer dependency and set up the right owner to the retrieved files.

   composer install --prefer-dist --no-dev
   

8. Refer to the UPGRADE.md and CHANGELOG.md files in the application repository for a list of changes in the code that may affect the upgrade of some customizations.

9. Remove old caches.

   rm -rf var/cache/*
   

10. Upgrade the platform.

php bin/console oro:platform:update --env=prod

Note

To speed up the update process, consider using --schedule-search-reindexation or --skip-search-reindexation option:

• --schedule-search-reindexation — postpone search reindexation process until the message queue consumer is started (on step 12 below).

• --skip-search-reindexation — skip search reindexation. Later, you can start it manually using commands oro:search:reindex to update search index for the specified entities and oro:website-search:reindex to rebuild storefront search index. See Search Index: Indexation Process.

Note

When the following options are not provided, they are set up automatically for the test environment:

• –force

• –skip-assets

• –skip-translations

• –timeout=600

The verbose mode is always set to debug in the test enviroment.

11. Remove the caches.

    php bin/console cache:clear --env=prod
    

    or, as alternative:

    rm -rf var/cache/*
    php bin/console cache:warmup --env=prod
    

12. Enable cron.

    crontab -e
    

    Uncomment this line.

    */1 * * * * /usr/bin/php <application-root-folder>/bin/console --env=prod oro:cron >> /dev/null
    

13. Switch your application back to the normal mode from the maintenance mode.

    php bin/console lexik:maintenance:unlock --env=prod
    

14. Run the consumer(s).

    php bin/console oro:message-queue:consume --env=prod
    

    Note

    If PHP bytecode cache tools (e.g., opcache) are used, PHP-FPM (or Apache web server) should be restarted after the uprgade to flush cached bytecode from the previous installation.

2. Download the Source Code Archive

To retrieve a new version and upgrade your Oro application instance, please execute the following steps:

1. Make sure that there are no changes that require the database schema update.

   php bin/console oro:entity-extend:update --dry-run --env=prod
   

   The platform update is possible only when the database schema is up-to-date.

2. Go to the Oro application root folder and switch the application to the maintenance mode.

   cd <application-root-folder>
   php bin/console lexik:maintenance:lock --env=prod
   

3. Stop the cron tasks.

   crontab -e
   

   Comment this line.

   */1 * * * * /usr/bin/php <application-root-folder>/bin/console --env=prod oro:cron >> /dev/null
   

4. Stop all running consumers.

5. Create backups of your Database and Code.

6. Download the latest version of the application source code from the download section on the website:

   • Download OroCommerce

   • Download OroCRM

   • Download OroPlatform

7. Unpack archive and overwrite existing system files.

   Note

   If you have any customization or third party extensions installed, make sure that:

   • your changes to src/AppKernel.php file are merged to the new file.

   • your changes to src/ folder are merged and it contains the custom files.

   • your changes to composer.json file are merged to the new file.

   • your changes to configuration files in config/ folder are merged to the new files.

   • upgrade the composer dependency and set up right owner to the retrieved files.

     composer update --prefer-dist --no-dev
     

8. Refer to the UPGRADE.md and CHANGELOG.md files in the application folder for a list of changes in the code that may affect the upgrade of some customizations.

9. Remove old caches.

   rm -rf var/cache/*
   

10. Upgrade the platform.

php bin/console oro:platform:update --env=prod

11. Remove the caches.

php bin/console cache:clear --env=prod

or, as alternative:

rm -rf var/cache/*
php bin/console cache:warmup --env=prod

12. Enable cron.

    crontab -e
    

    Uncomment this line.

    */1 * * * * /usr/bin/php <application-root-folder>/bin/console --env=prod oro:cron >> /dev/null
    

13. Switch your application back to normal mode from the maintenance mode.

    php bin/console lexik:maintenance:unlock --env=prod
    

14. Run the consumer(s).

    php bin/console oro:message-queue:consume --env=prod
    

    Note

    If PHP bytecode cache tools (e.g. opcache) are used, PHP-FPM (or Apache web server) should be restarted after the upgrade to flush cached bytecode from the previous installation.

Business Tip

Looking to harness the new trend of digital commerce? Check out our guide on a B2B marketplace platform.