SugarCRM SupportDocumentationSugar Versions8.08.0 ProfessionalSugar Professional 8.0 Installation and Upgrade Guide

Sugar Professional 8.0 Installation and Upgrade Guide

Overview

This documentation will go through the requirements and steps to install or upgrade an on-site Sugar instance (hosted on a local web server). The following instructions are intended for system administrators with access to the appropriate systems and knowledge of the technology being used.

Installing an On-Site Instance

Installing Sugar requires a web server running PHP and a database server. The following sections detail the requirements needed for installing Sugar on a local web server stack as well as the individual steps to install Sugar.

Installation Prerequisites

Sugar can run on a variety of stack configurations, but there are some general requirements that all configurations should meet to properly run Sugar. For more information regarding which platforms and database providers are supported by Sugar, please refer to the 8.0.x Supported Platforms documentation.

Please note that it is recommended to install your Sugar instance with SSL security using a signed certificate to enable secure HTTPS access.

PHP Requirements

In addition to having a supported version of PHP installed, Sugar also requires several specific PHP modules and settings. Verify that the following modules and extensions are installed in your PHP configuration by checking the php.ini file or by executing a http://us.php.net/manual/en/function.phpinfo.php output:

  • bcmath
  • curl
    Note: We recommend using cURL 7.19.0 or later.
  • gd with FreeType
  • gmp
  • hash
  • imap
  • json
  • mbstring
  • mcrypt
  • openssl
  • SimpleXML
  • zip
  • zlib 

Sugar also requires one of the following extensions or settings to provide a source of CSPRNG for random tokens, in order of preference:

  • libsodium extension
  • open_basedir : If this setting is enabled, the following settings are recommended:
    • The use of /dev/urandom should be allowed.
    • Configure the temp directory to be used by the web server in php.ini (system_temp_dir = "/<temp directory>").
    • Add the path for this temp directory to the allowed open_basedir paths in php.ini (open_basedir="/var/www/html/sugar:/<temp directory>").
    • Optionally, configure the upload_tmp_dir and append that path to the allowed open_basedir paths as well.
  • mcrypt extension
  • com_dotnet extension

The following are some directives and their recommended values to be set in the php.ini file of your PHP configuration:

Directive PHP Default Recommended Description
date.timezone   Set according to your needs The timezone to use by default for date and time functions. View the list of possible time zones here: http://www.php.net/manual/en/timezones.php
display_errors 1 0 Determines if errors will be printed on the web page as part of the output or if they are hidden.
fastcgi.logging 1 0 Determines if SAPI logging is on or off when using FastCGI. FastCGI logging should be disabled when running on IIS.
max_execution_time 30 120 Determines the maximum amount of time in seconds that a script can run. This helps prevent the server being occupied by a long-running script. 
max_input_time -1 120

Determines the maximum amount of time in seconds that a script can analyze input data such as POST and GET. The default value of "-1" specifies that the max_execution_time will be used instead.

mbstring.func_overload 0 0

Overloads a set of single-byte functions by the mbstring counterparts. If this setting is not set to "0" you may experience unexpected results when using mbstring functions.

memory_limit 128M 512M

Determines the maximum memory size in bytes that a script can be allocated. This helps prevent a script from using all of the available memory.

post_max_size 8M 100M Determines the maximum size in megabytes of post data allowed. This is primarily important for file uploads as if the file is larger than this value the upload will fail. This value should mirror the setting for upload_max_filesize and may be set to a larger value if your users routinely upload large files.
session.use_cookies 0 1 Determines whether or not the session can use cookies
session.cookie_httponly 0 1 Determines whether PHP session cookies will be marked HTTPOnly which is recommended for security reasons.
session.cookie_lifetime 0 The default value is acceptable but can be adjusted according to your needs Determines the lifetime of a PHP session in seconds. The value 0 specifies the session will be active until the browser is closed.
session.gc_maxlifetime 1440 The default value is acceptable but can be adjusted according to your needs Determines the number of seconds after which data in the session will potentially be removed.
session.use_trans_sid 0 0 Determines whether transparent sid support is enabled or not.
upload_max_filesize 2M 100M Determines the maximum size in megabytes of an uploaded file. This value should mirror the setting for post_max_size and may be set to a larger value if your users routinely upload large files.

It is recommended to use memcached or Redis as the PHP session storage if your deployment involves more than one web server.

For more information regarding PHP directives and their function, please refer to www.php.net.

Database Requirements

Prior to installation, Sugar requires a supported database to already be running on your server. On top of a running database, there are some specific settings that need to be configured before Sugar can be installed. PHP needs to be configured with the proper drivers to communicate with the database of your choice.

Use the following steps to configure PHP to be able to access your database:

  1. Obtain the proper driver files corresponding to your database, server architecture, and PHP version.
    Database Extension Driver Location
    MySQL mysqli http://us.php.net/manual/en/book.mysqli.php
    Microsoft SQL sqlsrv http://msdn.microsoft.com/en-us/library/cc296170.aspx
  2. Place the driver files into PHP's extension_dir folder.
  3. Add an extension line into your php.ini file loading the driver file (e.g. extension=php_mysqli.dll).
  4. Restart your web server.

Note: If you are running MySQL version 5.7.5 or greater, update the [mysqld] section of my.cnf as follows before restarting MySQL as the default values are not compatible with Sugar:

sql_mode = "STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION"

For more information regarding which database platforms and versions are supported by Sugar, please refer to the 8.0.x Supported Platforms documentation.

Since Sugar 8.0 supports stored procedures for MySQL, please be sure to export all of the database including the stored procedures when installing and backing up your Sugar instance.

Web Server Requirements

Sugar requires some specific configuration regarding the supported web server on which it is being installed. Sugar creates and maintains many files in the Sugar directories; therefore, Sugar requires some very specific file permissions settings in order to install. The user the web server is running under needs to have read and write permissions on many Sugar files. At a minimum, the following files and directories need to be writable from your web server:

  • ./config.php
  • ./config_override.php
  • ./sugarcrm.log
  • ./cache/ and all subdirectories and files
  • ./custom/ and all subdirectories and files
  • ./data/ and all subdirectories and files
  • ./modules/ and all subdirectories and files

Please refer to the appropriate section below for additional requirements for your Linux, Windows, IIS, or Apache server.

Note: If you are planning to use a Real User Monitoring (RUM) agent, this may cause issues when fetching data from the REST APIs as additional data may be appended to JSON responses coming from the server causing errors.

Linux Server Installation Requirements

Sugar running on Linux expects the listed files and directories to be owned by the same user running the web server and to also be in the same group. Sugar would then require the following permissions:

  • 775 for the directories listed above
  • 664 for the config.php file and all files in the directories listed above

To set the permissions on Linux you can execute the following commands modified to replace apache and apache with your web server user and group: 

chown apache:apache -R <Sugar Directory>
chmod 755 -R <Sugar Directory> 
Windows Server Installation Requirements

Sugar running on Windows requires an updated certificate for the cURL library. Edit php.ini to add curl.cainfo=c:\php\cacert.pem, place this cacert.pem file in the c:\php\ directory on your server, and restart your web server.

Sugar running on Windows also requires fileinfo.dll to be enabled. Please refer to this documentation on the PHP site for more information.

IIS Server Installation Requirements

Sugar running on IIS requires the PUT and DELETE verbs to be enabled. 

Sugar running on IIS 8 and greater also requires the IIS virtual user responsible for running Sugar to be added to the Sugar instance directory's file access control list and given full control. In most cases, "DefaultAppPool" should be added, but the specific virtual user running your Sugar instance may differ and should be confirmed first. Restart IIS after changing the permission. Please refer to this documentation on the IIS site for more information.

Sugar running on IIS must also have the URL Rewrite module installed in order for the web server to read the web.config file and generate the correct redirects. For more information on IIS URL Rewrite, please refer to the IIS site.

For IIS environments, Sugar recommends the following configurations for FastCGI:

  • Activity Timeout : 3600
  • Request Timeout : 3600
Apache Server Installation Requirements

Sugar running on the Apache web server requires a setting configured in the httpd.conf file. Modify the AllowOverride value for the Sugar installation directory to be set to All. Installation and upgrade will fail if AllowOverride is not configured in Apache.

Please note that mod_rewrite must also be enabled in Apache in order for Sugar to function properly.

It is recommended to configure the Apache modules mod_headers and mod_expires on your Sugar application server. While not strictly required to run Sugar, they can be used together by the Sugar application to ensure that HTTP Caching is applied properly on static resources such as image files which improve performance by reducing web traffic. For more information, please refer to the HTTP Caching documentation on the Google Developer site.  

To prevent performance issues, also add compression offloading if you have a load balancer or mod_deflate if you do not have a load balancer. For more information on mod_deflate, please refer to the mod_deflate documentation on the Apache site.

Your web server can have timeout configurations that may interrupt PHP execution; Apache has a Timeout directive. For more information, please refer to the documentation for your specific web server.

Elasticsearch Requirements

Elasticsearch is the built-in support engine for full-text search and is a required stack component when installing Sugar. The following resources are available for Elasticsearch:

Please note that only certain versions of Elasticsearch are supported by Sugar. For more information regarding the supported versions, please refer to the 8.0.x Supported Platforms documentation.

Once Sugar is installed, administrators will have the ability to schedule a full system index via Admin > Search as necessary. Please note that cron must be configured for the scheduler in order for the full system index to run properly in Sugar.

Switching Elasticsearch Versions for Sugar Upgrades

Most earlier versions of Sugar required Elasticsearch (ES) 1.7.5. But versions of Sugar 8.x and higher require a newer version of ES. Specifically, Sugar 8.0.0 requires Elasticsearch 5.4 or 5.6. For information about which versions of Elasticsearch are supported for your Sugar installation, please refer to the 8.0.x Supported Platforms documentation. Please note that, after switching to Elasticsearch 5.x and subsequently upgrading Sugar, your existing Elasticsearch indices will be gone so you must recreate them by running a complete re-index of your full-text search data.

Note: SugarCRM does not support the installation, upgrade, or configuration of stack components such as Elasticsearch.

The following steps explain how to move from Elasticsearch 1.7.x to 5.x as an example.

    1. Follow the instructions written in the Installing and Administering Elasticsearch article to install Elasticsearch 5.x on a new port on your server. For this example, we have installed Elasticsearch 5.6 on localhost port 9250 because Elasticsearch 1.7.5 is installed to port 9200, as seen in the following lines from our config.php:
      $sugar_config['full_text_engine']['Elastic']['host'] = 'elastic_server_address_1_7';
      $sugar_config['full_text_engine']['Elastic']['port'] = '9200';
    2. Take a moment to check the mappings and the number of documents in elastic_server_address_1_7. Later, you can use the information to confirm that everything has reindexed successfully.
    3. Modify the previously mentioned lines in config.php to point to the host and port of the new installation of Elasticsearch:
      $sugar_config['full_text_engine']['Elastic']['host'] = 'elastic_server_address_5_6';
      $sugar_config['full_text_engine']['Elastic']['port'] = '9250';
    4. Now upgrade your instance to Sugar 8.0 using Silent Upgrader or Upgrade Wizard as described in this page.
    5. Next, ensure cron is enabled for your instance and then cycle cron using one of the following methods to re-index your data:
      • Navigate to Admin > Search and run a complete re-index.
      • Alternatively, use the following command to cycle cron via CLI:
        php -f cron.php
    6. Finally, after the re-index, confirm that the mappings and the number of documents in elastic_server_address_5_6 is consistent with what you noted in step 2.

Note: You must re-index the search data (step 5) for searches to work in your upgraded version of Sugar.

Downloading Sugar

Use the following steps to download the required files to install Sugar:

  1. Navigate to the SugarCRM Support site
  2. Click the Log In button on the top of the page.
    DownloadingSugar Login
  3. Enter your SugarCRM.com credentials and click "Login".
    DownloadingSugar LoginScreen
  4. Once you are logged in with your SugarCRM.com account, you should automatically return to the SugarCRM Support site. Click the Resources tab on the navigation bar. 
    InstallGuide DownloadingSugar SupportPage Resources
  5. On the Resources page, select "Managing Your Sugar Subscription" under the Customer Resources section. Then navigate to the "How do I download the software I bought?" section and click the Downloads page link.
    DownloadingSugar Support Resources DownloadPurchasedSoftware 
  6. On the Download page, select the appropriate edition (e.g. Professional) of Sugar from the dropdown.
    • Note: You will only be able to select editions of Sugar that are tied to your SugarCRM.com account.
      DownloadingSugar DownloadManager EditionSelection 7.7 
  7. The most recent version of Sugar available for your account will be displayed at the top of the page. Click the desired version link to expand the list of available files.
    • Note: Please keep in mind that there may be versions listed in the download manager which are no longer supported. Please verify that the version desired is supported by checking the Supported Versions page.
      Downloads
  8. Download the installer zip file for your desired version by clicking the appropriate link under the Installers section.
  9. The installer zip file will be downloaded to your computer. 

Preparing Installation

After downloading the installer zip file for Sugar you will need to extract the contents of the zip file into the root directory of your web server. Use the following steps to prepare the files for installation:

  1. Transfer the installer zip file to the web server where Sugar is to be installed.
  2. Locate the web root directory on the web server. This directory is where files to be served will be located. The following are common locations for the web root directory but may differ depending on your server configuration:
    • Linux/Apache : /var/www/html/
  3. Extract the installer zip file's contents into the web root. This will create a directory in the web root indicating which edition and version of Sugar is in the contents (e.g. SugarUlt-Full-8.0.0).
  4. Rename this directory to match the intent of the install (e.g. sugarcrm, sugarcrm_dev, sugarcrm_test).
  5. Set the permissions on the files within the Sugar directory as described in the Web Server Requirements section above.

Installing via Setup Wizard

After preparing the installation files, you are ready to install Sugar. Use the following steps to install Sugar via the Setup Wizard.

Note: It is recommended that you install your Sugar instance with SSL security using a signed certificate to enable secure HTTPS access.

  1. Using a supported web browser, navigate to the primary URL for your Sugar directory:
    http://{Your Web Server}/{Your Sugar Directory} (e.g. http://localhost/sugarcrm/).
  2. The Setup Wizard will launch and bring you to the Welcome page.
  3. Select the primary language you wish to have the Setup Wizard use then click "Next" to proceed.
    8.0 SetupWizard
  4. Review the information on the following page to ensure all of the proper steps have been taken to perform a successful install. Click "Next" to continue.
  5. Review the License Subscription Agreement and select "I Accept". Click "Next" to continue.
    8.0 SetupWizard LicenseAcceptance
  6. The Setup Wizard will now check your server environment for compatibility. If your environment passes, the installation will continue. Otherwise, you will be prompted to correct any issues before proceeding. Once the issues have been resolved, click "Re-check" to perform the compatibility check again and continue with the installation.
    InstallAndUG_InstallingViaSetupWiz_SystemCheckAcceptance
  7. On the Installation Options page, enter in your download key then select the install type. Click "Next".
    • Typical Install : Provides minimal configuration options for a simple install.
    • Custom Install : Provides additional configuration options such as Sugar URL, System Name, and Collation.
    Setup_Wizard_5_Key_Type_Next
  8. On the Database Type page, select the database platform you wish to install your Sugar instance. The listed database types generate from the database drivers currently installed in PHP on the server. If you do not see your expected database engine, please check your PHP configuration and restart your web server to reflect any changes made in the configuration. Click "Next" to continue.
    SetupWizardInstallation DatabaseType
  9. On the Database Configuration page, enter appropriate values for the following fields then click "Next" to continue:
    Note: All required fields are marked with a red asterisk and must be completed prior to continuing.
    • Database Name : Name or designation of the database to be created and used with this installation of Sugar. If the database name entered is an existing database on the specified server, the existing database and its contents will be deleted and replaced with the Sugar database.
    • Host Name : Name of the server or machine where the database will be created and used with this installation of Sugar.
    • Database Administrator Username : Provide the user name of an administrative user who has proper permissions to create databases and tables on the specified database server.
    • Database Admin Password : Provide the password of the specified administrative user.
    • Sugar Database Username : Select an option from the dropdown to determine the database user Sugar will connect with.
    • Enable SSL Connection : Select "Yes" to allow Sugar to connect to the database using SSL.
    • Populate Database with Demo Data? : Select "Yes" to populate the database with demo records for testing Sugar.
    • Search Engine Type : The Elasticsearch server is required to install Sugar and is selected by default. 
      • Same as Admin User : Sugar will use the already provided database user name and password to connect to the database.
      • Provide existing user : Enter credentials for a different database user for Sugar to connect to the database.
      • Define user to create : Enter credentials to create a new user for Sugar to connect to the database.
      • Host : Enter the host name or IP address of the full-text search engine. Defaults to "localhost" assuming you are running the search engine on the same server as Sugar.
      • Port : Enter the port number for communicating with the full-text search engine. Defaults to "9200", which is Elasticsearch's default.
  10. On the Site Configuration page, enter appropriate values for the following fields:
    • Sugar Application Admin Name : The Sugar administrative user name that you will use to log in for the first time upon successful installation. Defaults to admin.
    • Sugar Admin User Password : A password for the Sugar administrative user that you will use to log in for the first time upon successful installation.
    • Re-enter Sugar Admin User Password : A confirmation of the provided password to ensure it was entered correctly.
  11. If you are performing a custom install instead of a typical install, the following fields will also need to be completed on the Site Configuration page:
    • URL of Sugar Instance : Enter the URL used to access your Sugar instance. This value is important for various integrations to function properly and is generally desired to be a publicly accessible URL where possible.
    • System Name : Enter the name of your Sugar instance to be displayed in the browser title bar.
    • Collation Settings : Select the proper collation setting to use when creating the database tables. The collation determines the character set and default sorting options. Defaults to "utf8_general_ci".
  12. Click "Next" to continue.
    Note: If you are performing a typical install, you will be taken directly to the Confirm Settings page (Step 14). If you are performing a custom install, the Site Security page (Step 13) will open first instead.
    SetupWizardInstallation SiteConfiguration 
  13. Select your desired security option(s) on the Site Security page then click "Next" to proceed to the Confirm Settings page.
    • Automatically Check For Updates? : When selected, the system will periodically check for updates to Sugar versions.
    • Use a Custom Session Directory for Sugar : When selected, you can provide a secure folder for storing Sugar session information. This can be done to prevent session data from being vulnerable on shared servers or from conflicting with other session data stored on the server for other applications.
    • Use a Custom Log Directory : When selected, you can specify a directory to store the Sugar log. Regardless of where the log file is located, access to it through a web browser will be restricted via a .htaccess redirect.
    • Provide Your Own Application ID : When selected, you can provide an application ID to override the auto-generated ID. This ID should always be unique when compared to any other instances hosted on the same server. This value is utilized by PHP caching engines (e.g. APC, Memcache) to distinguish the proper files to serve.
  14. Review and confirm your settings on the Confirm Settings page then click "Install" to begin the install process. 
    • Click the Back button in order to navigate back to a previous step of the setup wizard and modify any of the settings.
    • Click the Show Passwords button if you wish to verify the "Sugar Database User Password" and the "Sugar Admin User Password" values on the page.
    • Click the Print Summary button if you wish to print the summary of your configuration settings. 
      SetupWizardInstallation ConfirmSettings Install
  15. The Perform Setup page will display the install results and indicate when the setup of Sugar is complete. Click "Next" to continue.
  16. If the Custom Install option was selected on Step 7, you will be given the option to install language packs. But you can also install language packs through the application at a later time. Click "Next" to continue.
  17. If you wish to register your information with SugarCRM, complete the fields on the following Registration page. If you wish to skip this step, click "Next".

The Sugar login page will now open and you can log in to your instance using the admin username and password provided during the setup.

Upgrading an On-Site Instance

To get the most out of Sugar we recommend being on the latest version. Newer versions of Sugar come with increased performance, bug fixes, and new features in general. Before upgrading Sugar it is highly recommended that the upgrade be run on a test or backup copy of your production system first. This will not only allow you to be familiar with the process but can also point out any potential issue(s) you may encounter when upgrading your production instance.

Upgrade Prerequisites

Before performing an upgrade, please ensure that the following requirements are met to ensure a successful upgrade:

  • Only instances running 7.9.4.0 are eligible for upgrade to 8.0.0.
  • Be sure that all platform components are updated in accordance with the 8.0.x Supported Platforms before upgrading.
  • Install and properly configure Elasticsearch version 5.4 or 5.6 before upgrading to Sugar 8. For instructions, please refer to the Switching Elasticsearch Versions for Upgrades section.
  • Ensure that these PHP libraries and extensions are installed. 
  • If you are running on Windows, edit php.ini to add curl.cainfo=c:\php\cacert.pem, place this cacert.pem file in the c:\php\ directory on your server, and restart your web server.
  • Verify the PHP post_max_size and upload_max_filesize settings are sufficiently large for the upgrade files. Our recommendations are available in the PHP section above.
  • Verify that the user the web server is running under has read and write permissions to the Sugar directory as well as the config.php file in the Sugar directory.
  • If you have made code-level changes to a file, verify the changes are upgrade-safe (i.e. are located in the custom directory) or they may be removed during the upgrade.
  • If op-code caching is enabled in PHP, disable it to ensure cached code is not used during the upgrade. Op-code caching can be re-enabled after the upgrade is complete.
  • If you are using Zend Core 2.0, increase the values for ConnectionTimeout to 3000 seconds and RequestTimeout to 6000 seconds.
  • If you are running on Apache, set the LimitRequestBody value in the httpd.conf file to 2GB.

Upgrading via Upgrade Wizard

The Upgrade Wizard allows administrators to quickly and easily upgrade their Sugar instance to a newer version. Please note that the Upgrade Wizard is only available to administrative users and can be accessed via Admin > Upgrade Wizard. Before running the upgrade in Sugar, please be sure to create a backup of your file directory and database.

First, ensure you have completed the upgrade prerequisites listed above.

The health check scanner will run as part of the upgrade process when upgrading to 8.0.x to ensure that your instance is suitable for upgrade. If any issues (red flags) are detected that are deemed incompatible for the upgrade, the health check will fail and you will not be able to proceed with the upgrade until the issues have been resolved. If you wish to evaluate your instance's readiness for an upgrade prior to performing the upgrade, please proceed through the first two sections below and exit the upgrader after completing the health check.

Note: If your database contains more than 10,000 records per table, we recommend Upgrading via Silent Upgrader instead of using the Upgrade Wizard. Manual upgrades by file replacements and running SQL upgrade statements are not supported. 

The following sections walk through the steps required to perform an upgrade using the Upgrade Wizard:

  1. Complete the upgrade prerequisites.
  2. Perform a health check.
  3. Perform the upgrade.

Performing the Health Check

To evaluate whether your instance is suitable for upgrade to 8.0 without committing to the actual upgrade, please use the following steps. If you wish to complete the upgrade to 8.0 including the health check, please proceed to the Performing the Upgrade section below.

  1. Navigate to your available downloads using Steps 1 - 8 on the Downloading Sugar section to obtain the appropriate upgrade zip file.
    • Note: The upgrade files can be found under the Upgrade Packages section and specify the "from" and "to" versions of Sugar in the file name. The from version must match your current version of Sugar in order to successfully perform the upgrade. For example, to upgrade a 7.9.4.0 instance of Sugar Professional to 8.0.0, you would need the SugarPro-Upgrade-7.9.4.0-to-8.0.0.zip file.
  2. Navigate to Admin > Upgrade Wizard.
  3. In Step 1 of the upgrade wizard, click the Choose File button and select the appropriate upgrade file from your local machine then click "Upload". The health check will now begin to run. 
    SugarUpgrader UploadButton
  4. Step 2 of the upgrade wizard will display the health check results marked by different colored icons.
    • Green Checkmark : Health check passed. Any customizations detected in your instance marked with a green checkmark will be upgraded properly. 
    • Yellow Ellipsis : Health check passed. Outputs are generated which require attention. Should you choose to proceed with the upgrade, please keep in mind that customizations were found in your instance that may:
      • Prevent certain modules from getting upgraded to Sugar 8's Sidecar user interface and will be available with the Legacy user interface.
      • Be modified or disabled to facilitate the upgrade of certain modules to Sugar 8's Sidecar user interface.
    • Red Exclamation Point : Health check failed. Any issues deemed incompatible for the upgrade will need to be resolved before proceeding with the upgrade. You can also click the Export Log button to view the log file and troubleshoot the issue.
      • Note: If any customizations have been made since the last successful health check, please be sure to run the health check again before performing the upgrade.
    Healthcheck Step2 Success
  5. Click the Go to Home Page button to exit the upgrade process and navigate to the Home page. If you wish to proceed with the upgrade now, click the Confirm button. Please note that the Confirm button will be disabled if any issues deemed incompatible for upgrade are detected.

Performing the Upgrade

After upgrading to Elasticsearch 5.4 or 5.6 (required for 8.0.x and higher) and completing the other upgrade prerequisites and health check, use the following steps to perform an upgrade using the Upgrade Wizard.

Note: If you have just performed a health check, you can skip to Step 5.

  1. Navigate to your available downloads using Steps 1 - 8 on the Downloading Sugar section to obtain the appropriate upgrade zip file.
    • Note: The upgrade files can be found under the Upgrade Packages section and specify the "from" and "to" versions of Sugar in the file name. The from version must match your current version of Sugar in order to successfully perform the upgrade. For example, to upgrade a 7.9.4.0 instance of Sugar Professional to 8.0.0, you would need the SugarPro-Upgrade-7.9.4.0-to-8.0.0.zip file. 
  2. Navigate to Admin > Upgrade Wizard.
  3. Click the Choose File button in the Sugar Upgrader screen to open a file selection window from your browser.
  4. Select the upgrade file from your local machine then click "Upload".
    Performing Upgrade File Upload
  5. The health check will be performed to ensure your instance is ready for an upgrade. If you performed the health check just prior to running the upgrade and resolved any issues (if applicable) to pass the health check, you should successfully pass the health check again. Click "Confirm" to proceed with the upgrade. Please note that the Confirm button will be disabled if any issues deemed incompatible for upgrade are detected.
    PerformingtheUG Step2 Success 
  6. A progress bar will display on the following screen showing each step (Upload the upgrade package, Healthcheck, Pre-upgrade, Upgrade, etc.) being completed. 
    PerformingtheUG Step3 UpgradeComplete  

Once your instance has been upgraded, you can click the Export Log button to review the log file for the upgrade or click the button labeled "Go to Home Page" to log in to the Sugar instance.

Upgrading via Silent Upgrader

The Silent Upgrader is a command line script that enables administrators to avoid some limitations of the server environment PHP and potentially the web server with settings that can put too tight of restrictions on the upload size or session timeouts. The Silent Upgrader either avoids the limitations or better controls the settings in its stand-alone execution environment.

First, complete the upgrade prerequisites listed above.

The health check scanner will run as part of the upgrade process to ensure that your instance is suitable for the actual upgrade. If any issues (red flags) are detected that are deemed incompatible for the upgrade, the health check will fail and you will not be able to proceed with the upgrade until the issues have been resolved. If you wish to evaluate your instance's readiness for an upgrade prior to performing the upgrade, please proceed through the first two sections below and exit the upgrader after completing the health check.

Please ensure that you are executing the Silent Upgrader scripts as the web server user. The Silent Upgrader script creates new files for the user logged in running the script. For example, for the root user, it creates files as user/group root. Since Apache cannot read this, you must ensure that the web server user has the permissions to read and write the script.

The following sections walk through the required steps to perform an upgrade using the Silent Upgrader:

  1. Complete the upgrade prerequisites.
  2. Download the files.
  3. Perform a health check.
  4. Perform the upgrade.

Downloading the Necessary Files

  1. Navigate to your available downloads using Steps 1 - 8 on the Downloading Sugar section to obtain the appropriate silent upgrade file.
    • Note: The silent upgrade files can be found under the Command Line Upgrader section and will specify the "to" version of Sugar in the file name. This version must match your future, desired version of Sugar, not your current version. For example, to silent upgrade a 7.9.4.0 instance of Sugar to 8.0.0, you would need the silentUpgrade-PRO-8.0.0.zip file. Please note that the silent upgrade file includes the phrase "PRO" for all editions.
    • Note: The upgrade file must be placed in a path that does not include any spaces in the name or there will be errors when performing the upgrade. 
  2. Also, download to your server the appropriate upgrade package which specifies both the "to" and "from" versions. For example, to upgrade a 7.9.4.0 instance of Sugar Professional to 8.0.0, you would need the SugarPro-Upgrade-7.9.4.0-to-8.0.0.zip file. Please note that these upgrade packages are edition specific.
    • Note: The upgrade file must be placed in a path that does not include any spaces in the name or there will be errors when performing the upgrade.
  3. Unzip the silent upgrade file.
    • Note: The upgrade package downloaded in Step 2 may also be unzipped if desired prior to performing the upgrade.

Performing the Health Check

  1. From the command line of the web server, navigate to the directory containing the above files downloaded and extracted in the Downloading the Necessary Files section above:
    php CliUpgrader.php -z <upgradePackage> -l <logFile> -s <pathToSugar> -u <adminUser> -m <mask> -b <backup> -S <stage> -A <autoConfirm>

    • Note: To invoke only the health check stage of the silent upgrade process, populate the parameters above with specific values for your situation:
      • <upgradePackage> : The full file path to the upgrade package.
      • <logFile> : The path to the log file to store the results of the silent upgrade. A relative path to the Sugar instance may be used.
      • <pathToSugar> : The full file path to the instance being upgraded.
      • <adminUser> : A valid Sugar administrative user name.
      • <mask> : Script mask specifying which types of scripts to run. Supported types include: core, db, custom, all, and none. The default value is 'all'.
      • <backup> : Determines whether a backup of deleted files will be made with a default of "1" (true). Changing the option to "0" will not create a backup while.
      • <stage> : Instructs the upgrader to begin at a specific stage; "healthcheck" will cause only the health check portion to run while "continue" will cause it to start where it stopped on the previous run.
      • <autoConfirm> : Determines whether the confirmation prompt to continue with upgrade is bypassed and allows upgrade to automatically proceed when health check passes with a green or yellow flag. The option defaults to "0" (false). Change the option to "1" to enable the autoconfirm and proceed directly to upgrading after the health check. Do not alter this option when attempting to only run the health check without also completing an upgrade.
      For example, when running Sugar on a Linux-based server where your web root directory is located at /var/www/html/sugarcrm and the upgrade zip file and extracted files are all located at /home/users/<yourUserName>/sugarupgrade, use the following commands to perform a silent upgrade with the user "admin" and a log file of "silentUpgrade_800.log":
      cd /home/users/<yourUserName>/sugarupgrade/ 
      
      php CliUpgrader.php -z /home/users/<yourUserName>/sugarupgrade/SugarPro-Upgrade-7.9.4.0-to-8.0.0.zip -l ./silentUpgrade_800.log -s /var/www/html/sugarcrm/ -u admin -S healthcheck
  2. The health check's results will display whether the health check passed or failed for your instance.
    • Green Flag : Health check passed without errors or warnings. Please refer to the log file if you wish to view details of the health check.
    • Yellow Flag : Health check passed with errors or warnings. Please refer to the log file if you wish to view any errors or details of the health check. Should you choose to proceed with the upgrade, please keep in mind that customizations were found in your instance that may:
      • Prevent certain modules from getting upgraded to Sugar 8's Sidecar user interface and will be available with the Legacy user interface.
      • Be modified or disabled to facilitate the upgrade of certain modules to Sugar 8's Sidecar user interface.
    • Red Flag : Health check failed. Issues deemed incompatible for upgrade must be resolved before proceeding with the upgrade. Please refer to the log file in order to view the errors and details of the health check.

Performing the Upgrade

After upgrading to Elasticsearch 5.4 or 5.6 (required for 8.0.x and higher) and completing the other upgrade prerequisites and health check, use the following steps to perform an upgrade using the Silent Upgrader.

  1. From the command line of the web server, navigate to the directory containing the above files downloaded and extracted in the Downloading the Necessary Files section above:
    php CliUpgrader.php -z <upgradePackage> -l <logFile> -s <pathToSugar> -u <adminUser> -m <mask> -b <backup> -S <stage> -A <autoConfirm>

    • Note: To invoke the silent upgrade process with all the necessary stages (including health check), populate the parameters above with specific values in your situation and exclude the "-S" parameter:
      • <upgradePackage> : The full file path to the upgrade package.
      • <logFile> : The path to the log file to store the results of the silent upgrade. A relative path to the Sugar instance may be used.
      • <pathToSugar> : The full file path to the instance being upgraded.
      • <adminUser> : A valid Sugar administrative user name.
      • <mask> : Script mask specifying which types of scripts to run. Supported types include: core, db, custom, all, and none. The default value is 'all'.
      • <backup> : Determines whether a backup of deleted files will be made with a default of "1" (true). Changing the option to "0" will not create a backup while.
      • <stage> : Instructs the upgrader to begin at a specific stage; "healthcheck" will cause only the health check portion to run while "continue" will cause it to start where it stopped on the previous run.
      • <autoConfirm> : Determines whether the confirmation prompt to continue with upgrade is bypassed and allows upgrade to automatically proceed when health check passes with a green or yellow flag. The option defaults to "0" (false). Change the option to "1" to enable the autoconfirm and proceed directly to upgrading after the health check. Do not alter this option when attempting to only run the health check without also completing an upgrade.
      For example, when running Sugar on a Linux-based server where your web root directory is located at /var/www/html/sugarcrm and the upgrade zip file and extracted files are all located at /home/users/<yourUserName>/sugarupgrade, use the following commands to perform a silent upgrade with the user "admin" and a log file of "silentUpgrade_800.log":
      php CliUpgrader.php -z /home/users/<yourUserName>/sugarupgrade/SugarPro-Upgrade-7.9.4.0-to-8.0.0.zip -l ./silentUpgrade_800.log -s /var/www/html/sugarcrm/ -u admin
  2. The Health Check scanner will automatically run to evaluate whether your instance is ready for upgrade. The results will display whether the health check passed or failed for your instance:
    • Green Flag : Health check passed successfully and you can proceed with the upgrade. A message will display asking for confirmation (Yes or No) to proceed with the upgrade. Please refer to the log file if you wish to view details of the health check.
    • Yellow Flag : Health check passed and you can proceed with the upgrade. A message will display asking for confirmation (Yes or No) to proceed with the upgrade. Please refer to the log file if you wish to view any errors or details of the health check. Should you choose to proceed with the upgrade, please keep in mind that customizations were found in your instance that may:
      • Prevent certain modules from getting upgraded to Sugar 8's Sidecar user interface and will be available with the Legacy user interface.
      • Be modified or disabled to facilitate the upgrade of certain modules to Sugar 8's Sidecar user interface.
    • Red Flag : Health check failed and you cannot proceed with the upgrade. Issues deemed incompatible for upgrade must be resolved prior to upgrading. Please refer to the log file in order to view the errors and details of the health check.
  3. After the upgrade is completed successfully, fix ownership and permissions of Sugar's root directory:
    chown apache:apache -R <Sugar root directory>
    chmod 755 -R <Sugar root directory>
  4. Log in to Sugar and, as a final cleanup, navigate to Admin > Repair and perform "Quick Repair and Rebuild" and "Rebuild Relationships". For more information on the functions performed by the repair, please refer to the Repair documentation.

Your instance has now been upgraded to 8.0.

Converting Sugar Editions

The Upgrade Wizard allows administrators to easily convert their Sugar instance to a new edition (e.g. Professional to Enterprise) using a conversion zip file. Before running the conversion in Sugar, please be sure to create a backup of your file directory and database.

Note: The Silent Upgrader may also be used to convert to a new edition via the command line.

The health check scanner will run as part of the conversion process to ensure that your instance is suitable for conversion. If any issues (red flags) are detected that are deemed incompatible for conversion, the health check will fail and you will not be able to proceed with the conversion until the issues have been resolved.

The following table lists the editions that can be converted from and to in Sugar:

From Edition To Edition
Professional Enterprise, Ultimate
Enterprise Ultimate

Use the following steps to convert your Sugar instance (e.g. Professional) to a new edition (e.g. Enterprise):

  1. Navigate to your available downloads using Steps 1 - 8 on the Downloading Sugar section to obtain the appropriate conversion zip file.
    • Note: The conversion files can be found under the Conversion Packages section of the Sugar edition (e.g. Enterprise) you wish to convert to and will specify the "from" and "to" editions of Sugar in the file name. The from edition must match your current edition of Sugar in order to successfully perform the conversion. For example, to upgrade a 7.9.4.0 instance of Sugar Professional to Sugar Enterprise 8.0.0, you would need the SugarPro-to-SugarEnt-Conversion-8.0.0.zip file.
  2. Navigate to Admin > Upgrade Wizard.
  3. In Step 1 of the upgrade wizard, click the Choose File button and select the appropriate conversion file from your local machine then click "Upload". The health check will now begin to run.
    UGWizard Step1 Upload
  4. Step 2 of the upgrade wizard will display the health check results marked by different colored icons. Click "Confirm" to proceed with the conversion.
    • Note: The Confirm button will be disabled if any issues deemed incompatible for conversion are detected.
      • Green Checkmark : Health check passed. Any customizations detected in your instance marked with a green check mark will be converted properly. 
      • Yellow Ellipsis : Health check passed. Outputs are generated which require attention. Should you choose to proceed with the conversion, please keep in mind that customizations were found in your instance that may:
        • Prevent certain modules from getting converted to Sugar 8's Sidecar user interface and will be available with the Legacy user interface.
        • Be modified or disabled to facilitate the conversion of certain modules to Sugar 8's Sidecar user interface.
      • Red Exclamation : Health check failed. Any issues deemed incompatible for conversion will need to be resolved before proceeding with the conversion. You can also click the Export Log button to view the log file and troubleshoot the issue.
      Conversion Healthcheck Success
  5. A progress bar will display on the following screen showing each step (Upload the upgrade package, Healthcheck, Pre-upgrade, Upgrade, etc.) being completed. Once the conversion is completed successfully, click the Go to Home Page button.
    • Note: You can click the Export Log button if you wish to view the log file for the conversion.
      Conversion UpgradeComplete
  6. Navigate to the About page in Sugar and it should now display "SugarCRM Enterprise, Version 8.0.0 (Spring '18)".

Uninstalling Sugar

Use the following steps to uninstall an instance of Sugar:

  1. Navigate to the web server where Sugar is installed and delete the Sugar root directory.
  2. Navigate to the Sugar database using a database management system or command line and delete the Sugar database from the server.

Note: It is highly recommended to create a backup of the file directory and database before deleting.

Advanced Configuration

After installing Sugar, there are some advanced configurations that you can take advantage of. During the installation, Sugar attempts to create a .htaccess file in the Sugar root directory. This file helps to ensure certain files are not accessible through a web browser. The contents of this file should contain:

# BEGIN SUGARCRM RESTRICTIONS
RedirectMatch 403 (?i).*\.log$
RedirectMatch 403 (?i)/+not_imported_.*\.txt
RedirectMatch 403 (?i)/+(soap|cache|xtemplate|data|examples|include|log4php|metadata|modules)/+.*\.(php|tpl)
RedirectMatch 403 (?i)/+emailmandelivery\.php
RedirectMatch 403 (?i)/+upload/
RedirectMatch 403 (?i)/+custom/+blowfish
RedirectMatch 403 (?i)/+cache/+diagnostic
RedirectMatch 403 (?i)/+files\.md5$

# Fix mimetype for logo.svg (SP-1395)
AddType     image/svg+xml     .svg
AddType     application/json  .json
AddType     application/javascript  .js

<IfModule mod_rewrite.c>
    Options +FollowSymLinks
    RewriteEngine On
    # Replace <basepath> with the relative web root path to your instance
    RewriteBase /<basepath>
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^rest/(.*)$ api/rest.php?__sugar_url=$1 [L,QSA]
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^cache/api/metadata/lang_(.._..)_(.*)_public\.json$ api/rest.php/v10/lang/public/$1?platform=$2 [L,QSA]
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^cache/api/metadata/lang_(.._..)_([^_]*)\.json$ api/rest.php/v10/lang/$1?platform=$2 [L,QSA]
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^cache/Expressions/functions_cache(_debug)?.js$ api/rest.php/v10/ExpressionEngine/functions?debug=$1 [L,QSA]
</IfModule>

<FilesMatch "\.(jpg|png|gif|js|css|ico|woff|svg)$">
        <IfModule mod_headers.c>
                Header set ETag ""
                Header set Cache-Control "max-age=2592000"
                Header set Expires "01 Jan 2112 00:00:00 GMT"
        </IfModule>
</FilesMatch>

<IfModule mod_expires.c>
        ExpiresByType text/css "access plus 1 month"
        ExpiresByType text/javascript "access plus 1 month"
        ExpiresByType application/x-javascript "access plus 1 month"
        ExpiresByType image/gif "access plus 1 month"
        ExpiresByType image/jpg "access plus 1 month"
        ExpiresByType image/png "access plus 1 month"
</IfModule>

# END SUGARCRM RESTRICTIONS

To verify these restrictions are in place in your instance, attempt to navigate to the sugarcrm.log file through a supported web browser (http://{Server Location}/sugarcrm/sugarcrm.log). If the restrictions are properly in place, you will receive a #403 Forbidden error. If you do not receive this error, you are either missing the .htaccess file or your web server is not configured to allow a .htaccess file. For more information on enabling a .htaccess file for your web server, please refer to your web server provider's documentation.

Sugar comes with many different advanced configuration options such as:

  • System Configuration
  • Security Options
  • Performance
  • Disabling Automatic Searches
  • Elastic Search Configuration

For more information regarding these topics and more configuration options, please refer to the Advanced Configuration Options documentation.

Last modified: 2019-08-29 13:53:15