Upgrading

If you run into 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, deploying 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

2. Upgrading between SuiteCRM 8.x versions

This section only applies when upgrading to a version equal or greater to 8.2.x. This version introduced a new step in the upgrade process.

For upgrades to with version previous to 8.2.x see section #3. Upgrading between SuiteCRM 8.0.x to 8.1.x versions

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

2.3.1 Metadata merge modes

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

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

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



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

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



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

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

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

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

5. Possible Issues when Upgrading

An issue was found on the implementation of the upgrade command between the versions 8.1.08.1.1.

The issue is that when upgrading SuiteCRM 8 for a second time (i.e if you had upgraded from 8.0.28.0.48.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.

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

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