Important

You are browsing the documentation for version 3.1 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:

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.
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
```

Stop the cron tasks.

crontab -e

Comment this line .

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

Stop all running consumers.
Create backups of your Database and Code.
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>
```
Upgrade the composer dependency and set up the right owner to the retrieved files.
```
composer install --prefer-dist --no-dev
```
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.
Remove old caches.
```
rm -rf var/cache/*
```
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 the oro:search:reindex and oro:website-search:reindex commands. See Search Index: Indexation Process.

Remove the caches.

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

or, as alternative:

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

Enable cron.

crontab -e

Uncomment this line.

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

Switch your application back to the normal mode from the maintenance mode.
```
php bin/console lexik:maintenance:unlock --env=prod
```
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:

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.
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
```

Stop the cron tasks.

crontab -e

Comment this line.

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

Stop all running consumers.
Create backups of your Database and Code.
Download the latest version of the application source code from the download section on the website:
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
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.
Remove old caches.
```
rm -rf var/cache/*
```
Upgrade the platform.

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

Remove the caches.

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

or, as alternative:

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

Enable cron.

crontab -e

Uncomment this line.

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

Switch your application back to normal mode from the maintenance mode.
```
php bin/console lexik:maintenance:unlock --env=prod
```
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.