Upgrading

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

Before upgrading

Before running the upgrade, 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 upgrade process in a development instance and test. Only after testing, deploying the upgraded version on to a production instance
Before upgrading please make sure to create a backup of your instance code and database.

Upgrading between SuiteCRM 8.x versions

This section only applies for versions greater than 8.0.0-rc

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.

4. Open your instance

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

Upgrade for pre release-candidate versions

Upgrading from SuiteCRM 8 Beta 3 to SuiteCRM 8 RC

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.

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

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.

3. 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 RC package

There is a known issue when running the upgrade command from Beta 3 to the RC version.

The step to overcome that issue are explained next

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. Open your instance

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

Possible Issues when Upgrading

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.

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.