Before running the migration, please make sure your system complies with the new version compatibility matrix.
Check the Compatibility Matrix for complete information on compatible versions.
It is recommended that you run the migration process in a development instance and test. Only after testing, deploying the upgraded version on to a production instance
Before migrating please make sure to create a backup of your instance code and database.
Upgrade your SuiteCRM 7.x instance to the latest 7.12.x version
Make sure to go over any manual upgrade steps described on the release notes for each version
By default, the upgrade commands will set the error_reporting to a less strict mode to suppress warnings.
The error_reporting value set is E_ALL & ~E_DEPRECATED & ~E_STRICT & ~E_NOTICE & ~E_WARNING
If you want to apply a stricter mode you can specify the -vvv on each of the commands. This will set E_ALL on error_reporting
Please note that the migration process may remove any non core file/directories you have on your project under the public/legacy/ folder
Only run the migration if you have already upgraded your SuiteCRM 7.x instance to the latest 7.12.x version.
1 - Download the SuiteCRM 8.x target version migration package from SuiteCRM Releases
2 - Unzip the package contents to your SuiteCRM 8.x destination folder
3 - If needed re-set the correct permissions.
1 - Copy your SuiteCRM 7.12.x instance folder to the public folder on the SuiteCRM 8.x destination folder /path-to-suitecrm-8/public
2 - Rename the SuiteCRM 7.12.x copied folder to legacy
3 - If needed re-set the correct permissions.
Set the permissions on the files in a way that the command line user enough privileges to read and write
1 - On your SuiteCRM 8 instance root run: ./bin/console suitecrm:app:setup-legacy-migration
2 - You should be prompted to do the manual step for checking and updating values on legacy config
session_dir: you should update your session dir to ''. After migration you can re-configure the system to use a different session_dir
Please note that the SuiteCRM 8 configuration for the session_dir is different.
See the Session Configuration for more details.
site_url: you should update your site_url
You should update this value to be the address you are currently using to migrate and test the SuiteCRM 8.x migration
Please note that if you don’t have your vhost pointing to the public dir within your SuiteCRM 8 root folder, you should append /public
e.g. if your address is something like https://your-host/crm/public,
3 - You should be prompted to do the manual step for checking and updating values on the legacy .htaccess
RewriteBase
If you have your vhost pointing to legacy dir within the SuiteCRM 8 root folder. Then you should set RewriteBase /legacy
Otherwise, you should prepend the path until the public folder.
e.g. if your address is something like https://your-host/crm/public, then you should set RewriteBase /crm/public/public
On your SuiteCRM 8 instance root run: ./bin/console suitecrm:app:upgrade -t "<version>"
Where <version> is the name on the SuiteCRM 8 package you’ve downloaded, i.e. SuiteCRM-8.2.0
Example: ./bin/console suitecrm:app:upgrade -t SuiteCRM-8.2.0
When upgrading highly customized instances you may hit issues during this step. Make sure your customization’s code is php 7.4 compliant as a minimum.
On your SuiteCRM 8 instance root run: ./bin/console suitecrm:app:upgrade-finalize
In this finalize command you can specify the merge mode you want to use for merging metadata.
This can be changed by specifying the -m option on the suitecrm:app:upgrade-finalize command.
The keep mode is used by default.
Next you can find a description of each mode and how to use it.
1. Keep mode
This mode will keep the existing view metadata customizations. It will simply skip the metadata merge process.
This is the default mode
If you want to specify on the command you can run: ./bin/console suitecrm:app:upgrade-finalize -m keep
2. Merge mode
This mode will attempt to merge your current view metadata customizations with the new core view metadata for each module
The merged metadata is placed in the custom folder for the corresponding module public/legacy/custom/<Module>/metadata
A backup file of the previous version of the customizations is added to the same folder
You can use the merge mode by running ./bin/console suitecrm:app:upgrade-finalize -m merge
3. Override mode
This mode will override your current customizations with the new version of the core metadata.
Please note that this will delete your current customizations files in public/legacy/custom/<Module>/metadata
You can use the merge override mode by running ./bin/console suitecrm:app:upgrade-finalize -m override
If during the migration you used a user/group that is not the same as the ones used by apache (or other webserver) you should re-set the correct permissions
If all the above steps went as expected, you should now be able to login into your instance.
Content is available under GNU Free Documentation License 1.3 or later unless otherwise noted.