Upgrading

If you run into any issue when upgrading, please check the 'Possible Issues when Upgrading section'.

1. Before upgrading

  1. Before running the upgrade, please make sure your system complies with the new version compatibility matrix.

  2. It is recommended that you run the upgrade process in a development instance and test. Only after testing, deploy the upgraded version on to a production instance

  3. Before upgrading please make sure to create a backup of your instance code and database.

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

  5. Please note that the upgrade process may remove any non core file/directories you have on your project under the root folder or the public/legacy/ folder

  6. Before running any of the commands described next, please make sure your SuiteCRM 8 instance APP_ENV is set to APP_ENV=prod mode (check .env and '.env.local' files)

1.2. Upgrade restrictions

The following section(s) contains the restrictions there are when upgrading between versions

1.2.1. Upgrading from versions between 8.0.x - 8.1.x to version 8.3.x or greater

If you are on any version between 8.0.x - 8.1.x and you wish to upgrade to a version greater or equal to 8.3.x, you will first need to upgrade to 8.2.x and only after that can you upgrade to your target version (8.3.x or greater)

1.2.2. Upgrading to version 8.3.1

There was a bug when upgrading to version 8.3.1, which has been resolved on 8.4.0. For more info see the subsection 6.2 Upgrading to version 8.3.1 at the end of the page.

2. Upgrading to SuiteCRM 8.2.x+ versions

This section only applies when upgrading to a version 8.2.x or greater, i.e, 8.2.x, 8.3.x, etc

If you are currently on a 8.0.x/8.1.x release, please ensure you upgrade to the latest 8.2.x release, before continuing on to future versions. (ie: 8.3.x or greater)

For upgrades to versions prior to 8.2.x see section #3. Upgrading from SuiteCRM 8.0.x to 8.1.x versions

Before moving forward, please make sure you’ve read the restrictions on the #1.2. Upgrade restrictions section

2.1. Download the new version package

For upgrading between SuiteCRM 8.x versions there aren’t any upgrade specific packages. The upgrade is done using the installation package of the version we want to upgrade to.

1. Create the following folder on you current instance:

  • <your-suitecrm-8-root-folder>/tmp/package/upgrade

2. Download the SuiteCRM 8 target version installable package from https://suitecrm.com/download/

3. Place the package on the <your-suitecrm-8-root-folder>/tmp/package/upgrade folder

4. If needed re-set the correct permissions.

2.2. Run the upgrade command

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

The output should be something like:

Note: please ignore the libpng warning

SuiteCRM Upgrade
============

Running: check-package
step: check-package | status: done
Package found in path
Running: extract-package
step: extract-package | status: done
Package extracted
Running: check-permissions
step: check-permissions | status: done
Permissions checked
Running: install-upgrade-package
step: install-upgrade-package | status: done
Successfully installed package
Running: run-migrations
step: run-migrations | status: done
Successfully run migrations
Running: legacy-post-upgrade
libpng warning: Interlace handling should be turned on when using png_read_image
libpng warning: Interlace handling should be turned on when using png_read_image
libpng warning: Interlace handling should be turned on when using png_read_image
libpng warning: iCCP: known incorrect sRGB profile
libpng warning: Interlace handling should be turned on when using png_read_image
libpng warning: iCCP: known incorrect sRGB profile
libpng warning: iCCP: known incorrect sRGB profile
libpng warning: iCCP: known incorrect sRGB profile
libpng warning: Interlace handling should be turned on when using png_read_image
step: legacy-post-upgrade | status: done
Post Upgrade process complete
Running: clear-symfony-cache

2.3. Run the post upgrade command

On your SuiteCRM 8 instance root run: ./bin/console suitecrm:app:upgrade-finalize -t "<version>"

2.3.1 Metadata merge modes

In the 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

  • The default mode is to keep the existing view metadata customizations and will simply skip the metadata merge process.

  • 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

2.4. Re-set permissions

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

2.5. (Optional) Restart server to reset/clear php level cache

If you are using opcache, apcu or other php caches, you may need to restart your webserver for the new code to take effect.

2.6. Open your instance

If all the above steps went as expected, you should now be able to login into your instance.

2.6. Debugging

Check 5. Logs and debugging section for information on how to debug.

3. Upgrading from SuiteCRM 8.0.x to 8.1.x versions

This section only applies for versions greater than 8.0.0-rc to 8.1.x

3.1. Download the new version package

For upgrading between SuiteCRM 8.x versions there aren’t any upgrade specific packages. The upgrade is done using the installation package of the version we want to upgrade to.

1. Create the following folder on you current instance:

  • <your-suitecrm-8-root-folder>/tmp/package/upgrade

2. Download the SuiteCRM 8 target version installable package from https://suitecrm.com/download/

3. Place the package on the <your-suitecrm-8-root-folder>/tmp/package/upgrade folder

4. If needed re-set the correct permissions.

3.2. Run the upgrade command

1. 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.1.1

  • Example: ./bin/console suitecrm:app:upgrade -t SuiteCRM-8.1.1

The output should be something like:

Note: please ignore the libpng warning

SuiteCRM Upgrade
============

Running: check-package
step: check-package | status: done
Package found in path
Running: extract-package
step: extract-package | status: done
Package extracted
Running: check-permissions
step: check-permissions | status: done
Permissions checked
Running: install-upgrade-package
step: install-upgrade-package | status: done
Successfully installed package
Running: run-migrations
step: run-migrations | status: done
Successfully run migrations
Running: legacy-post-upgrade
libpng warning: Interlace handling should be turned on when using png_read_image
libpng warning: Interlace handling should be turned on when using png_read_image
libpng warning: Interlace handling should be turned on when using png_read_image
libpng warning: iCCP: known incorrect sRGB profile
libpng warning: Interlace handling should be turned on when using png_read_image
libpng warning: iCCP: known incorrect sRGB profile
libpng warning: iCCP: known incorrect sRGB profile
libpng warning: iCCP: known incorrect sRGB profile
libpng warning: Interlace handling should be turned on when using png_read_image
step: legacy-post-upgrade | status: done
Post Upgrade process complete
Running: clear-symfony-cache

2. Re-set permissions, if needed

3.3. Open your instance

Once all the above steps are complete, you should now be able to log into your instance of SuiteCRM.

4. Upgrade for pre release-candidate versions

Some bugs were found while testing the upgrade from Beta 3 to RC. The steps on this section explain how to workaround those problems. These issues have been fixed on the RC version.

Upgrading from SuiteCRM 8 Beta 3 to SuiteCRM 8 RC

4.1. Prepare for upgrade.

To overcome the issues mentioned above, you need to apply the following change on your code base.

1. Open the config/services/system/upgrades.yaml config file.

2. Add a tmp entry to the toKeep section.

It should look like this:

parameters:
  upgrades:
    toKeep:
      - 'cache'
      - 'extensions'
      - 'public/extensions'
      - 'public/legacy/modules'
      - 'public/legacy/custom'
      - 'public/legacy/cache'
      - 'public/legacy/upload'
      - 'public/legacy/Api/V8/OAuth2/private.key'
      - 'public/legacy/Api/V8/OAuth2/public.key'
      - 'public/legacy/config.php'
      - 'public/legacy/config_override.php'
      - 'public/legacy/config_si.php'
      - 'public/legacy/suitecrm.log'
      - 'public/legacy/install.log'
      - 'logs'
      - '.env.local'
      - '.env.local.php'
      - 'tmp'
    toExpand:

    ...

3. Run:

  • For dev mode run: composer install

  • For prod mode run: composer install --no-dev --prefer-dist --optimize-autoloader

4.2. Download the RC package

1. Create the following folder on you current instance:

  • <your-suitecrm-8-root-folder>/tmp/package/upgrade

2. Download the SuiteCRM 8 RC pre-built / installable package

3. Place the package on the <your-suitecrm-8-root-folder>/tmp/package/upgrade folder

4. If needed re-set the correct permissions.

4.3. Run the upgrade command

There is a known issue when running the upgrade command from Beta 3 to the RC version. The step to overcome this issue is explained next.

1. On your SuiteCRM 8 instance root run: ./bin/console suitecrm:app:upgrade -t "<version>"

  • Where <version> is the name on the SuiteCRM 8 RC package

The output of the command should be something like:

Note: please ignore the above libpng warning

SuiteCRM Upgrade
============

Running: check-package
step: check-package | status: done
Package found in path
Running: extract-package
step: extract-package | status: done
Package extracted
Running: check-permissions
step: check-permissions | status: done
Permissions checked
Running: install-upgrade-package
step: install-upgrade-package | status: done
Successfully installed package
Running: run-migrations
step: run-migrations | status: done
Successfully run migrations
Running: legacy-post-upgrade
libpng warning: Interlace handling should be turned on when using png_read_image
libpng warning: Interlace handling should be turned on when using png_read_image
libpng warning: Interlace handling should be turned on when using png_read_image
libpng warning: iCCP: known incorrect sRGB profile
libpng warning: Interlace handling should be turned on when using png_read_image
libpng warning: iCCP: known incorrect sRGB profile
libpng warning: iCCP: known incorrect sRGB profile
libpng warning: iCCP: known incorrect sRGB profile
libpng warning: Interlace handling should be turned on when using png_read_image
step: legacy-post-upgrade | status: done
Post Upgrade process complete

In the last step of the command you should get the following error

Running: clear-symfony-cache
PHP Fatal error:  Interface 'Stringable' not found in /<your-suitecr-8-path>/vendor/symfony/string/AbstractString.php on line 30

Symfony\Component\ErrorHandler\Error\ClassNotFoundError^ {#3095
  #message: """
    Attempted to load class "UnicodeString" from namespace "Symfony\Component\String".\n
    Did you forget a "use" statement for another namespace?
    """
  #code: 0
  #file: "./vendor/symfony/console/Helper/Helper.php"
  #line: 63
  trace: {
    ./vendor/symfony/console/Helper/Helper.php:63 { …}
    ./vendor/symfony/console/Helper/Helper.php:49 { …}
    ./vendor/symfony/console/Application.php:826 { …}
    ./vendor/symfony/console/Application.php:795 { …}
    ./vendor/symfony/http-kernel/EventListener/DebugHandlersListener.php:136 { …}
    ./vendor/symfony/error-handler/ErrorHandler.php:607 { …}
    ./vendor/symfony/error-handler/ErrorHandler.php:695 { …}
    Symfony\Component\ErrorHandler\ErrorHandler::handleFatalError() {}
  }
}

2. To overcome the above error you need to clear symfony cache

  • On your SuiteCRM 8 instance root, please run: ./bin/console cache:clear

3. Re-set permissions, if needed

4.4. Open your instance

If all the above steps went as expected, you should now be able to login into your instance.

5. Logs and debugging

5.1 Logs

The commands used during the upgrade provide some information of the steps and their execution result. However, this information is insufficient when errors occur.

There are some logs that may provide more information:

logs/upgrade.log

These are the logs that are generated by the upgrade log on SuiteCRM 8 side.

public/legacy/upgradeWizard.log

These are upgrade specific logs that are generated by the legacy part of the app. This file is generated during the legacy-post-upgrade step.

logs/<app-env-mode>/<app-env-mode>.log

The main app log. Its file path and name changes according to the value set on your APP_ENV. E.g. if it is set to prod the path will be logs/prod/prod.log

Most likely, this log will not have much upgrade information.

public/legacy/suitecrm.log

This is the main log location for the legacy part of the app. It may contain upgrade related logs, as well as other logs.

5.2 APP_ENV mode

When running the app in a production environment the APP_ENV in .env or in .env.local should be set to prod. However this mode has a high log level, meaning that not all the debug information will be logged.

One way to get more logs is to change APP_ENV to qa (this mode should only be used temporarily).

After the APP_ENV you may have to clear the symfony cache.

6. Possible Issues when Upgrading

6.1 Upgrade between the versions 8.1.0 → 8.1.1

An issue was found on the implementation of the upgrade command between the versions 8.1.0 → 8.1.1.

The issue is that when upgrading SuiteCRM 8 for a second time (i.e if you had upgraded from 8.0.2 → 8.0.4 → 8.1.1), then you will have come across the following error after having ran: ./bin/console suitecrm:app:upgrade -t "<version>"

CRITICAL  [php] Fatal Compile Error: require(): Failed opening required '/<pathtoSuiteCRM8>/cache/prod/ContainerZatgzYy/getConsole_ErrorListenerService.php'
(include_path='/<pathtoSuiteCRM8>/public/legacy/include/..:.:/usr/share/php')
["exception" => Symfony\Component\ErrorHandler\Error\FatalError^ { …}]

This issue is a result of Symfony cache clearing but then being called right after.

6.1.1 Resolution

This issue can be resolved by re-setting permissions and ./bin/console clear:cache within the SuiteCRM 8 root directory.

You should then be able to navigate to your application.

6.2 Upgrading to version 8.3.1

There was a bug with version 8.3.1 that caused the upgrade process to fail.

If you are on a version lower than 8.3.0, and you wish to upgrade to version 8.3.1, you will first need to upgrade to 8.3.0 and only after that can you upgrade to 8.3.1.

This issue has been resolved in version 8.4. Thus, if you want to go from 8.2.0 (or any version lower than 8.3.1) to 8.4.0+ you can do it directly.

Content is available under GNU Free Documentation License 1.3 or later unless otherwise noted.