Sugar Community Edition 6.5.0 Installation Guide

Overview

This page describes how to install and upgrade Sugar Community Edition. This information is intended for administrators. After installation, you can create users and perform other administrative tasks in Sugar.

Ensure that you have the appropriate components installed on your server before installing Sugar 6.5.0.

Installation prerequisites and guidelines

This section lists the memory, database, and software requirements for installation.

Note: Install the MB String module on your web server to support multi-byte characters.

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.

Memory requirements

Increase the value of the memory_limit parameter in the php.ini file as follows:

  • 32-bit installations: 256M or higher
  • 64-bit installations: 512M or higher

Note: Increase the memory limit to 384M or higher for 32-bit installations, 768M or higher for 64-bit installations, for demo data installations.

Database requirements

  • For MySQL, install version 5.0 or 5.1 to use with Sugar 6.5
  • For Microsoft SQL Server, download the SQL Server Driver for PHP version 3.0 (as per the instructions on the Microsoft website) and extract the contents to the /ext directory of the PHP installation

Select from the following DLLs as appropriate for the PHP version you are using:

Driver File
PHP Version
Thread Safe
Use with PHP .dll
php_sqlsrv_53_nts_vc6.dll
5.3
No
php5.dll
php_sqlsrv_53_nts_vc9.dll
5.3
No
php5.dll
php_sqlsrv_53_ts_vc6.dll
5.3
Yes
php5ts.dll
php_sqlsrv_53_ts_vc9.dll
5.3
Yes
php5ts.dll
php_sqlsrv_52_nts_vc6.dll
5.2
No
php5.dll
php_sqlsrv_52_ts_vc6.dll
5.2
Yes
php5ts.dll

Add the following line in php.ini to enable it:

extension=<dll_name>;

where dll_name is a driver file listed in the table above.

The driver also requires you to install the Microsoft SQL Server Native Client on the web server. Install the version for SQL Server 2008 even if you are installing on SQL Server 2005.

Securing your Sugar installation

To ensure that your Sugar installation is secure from unauthorized access, for Apache, it is recommended that you configure the system as described below.

Before you install Sugar, set AllowOverride to All for the Sugar installation directory in thehttpd.conf file. After you install Sugar, a .htaccessfile is created in your Sugar installation directory. This file contains the following content:

# 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)/+cache/+upload

# END SUGARCRM RESTRICTIONS

To test the validity of these restrictions, access the sugarcrm.log through the browser to ensure that error #403 is displayed. If not, check your Apache configuration to ensure that htaccess is enabled. For more information, check the Apache documentation.

Downloading and installing Sugar

If you are installing Sugar on your machine for the first time, follow the instructions in this section. If you have an earlier version of Sugar installed on your machine, refer to Upgrading Sugar for instructions on how to upgrade your Sugar instance.

Follow the steps listed below to install Sugar:

  1. Install the platform-appropriate (Linux or Windows) version of PHP, web server, and database on your machine.
  2. Download Sugar files.
  3. Copy the Sugar files to your web server. Check for dependencies and requirements, and set them.
  4. Navigate to the php.ini file located in your Sugar root directory and set the variables_order parameter to EGPCS.
  5. Restart the web server.
  6. Install Sugar Community Edition with the Sugar Setup Wizard.

Note: Step 5 (restarting the web server) is required only if you have modified the php.ini file.

Downloading the latest Sugar files

  1. Go to http://www.sugarcrm.com/.
  2. Navigate to Support & Training/Support Portal or visit http://www.sugarcrm.com/sugarshop/download.
  3. Login using your Sugar username and password.
  4. Click Download Purchased Software.
  5. Populate the Download Key field in the Download Manager page and click Submit.
  6. Click the link for the appropriate zip file to download it.
    For example, SugarCE-6.5.0.zip.

Copying Sugar files to web browser

After you download Sugar, you need to unzip the files and set permissions.

  1. Locate the webrootdirectory on your web server. This directory stores publicly accessible files. Common locations for webroot are:
    /var/www/html/ (Linux/Apache)
    C:\Inetpub\wwwroot\ (Windows/IIS)
    C:\Program Files\Apache Group\Apache\htdocs\ (Windows/Apache)
    /Library/Web server/Documents/ (MacOS X/Apache)
  2. Unzip the Sugar zip file into your webroot.
    This automatically creates a directory within webroot.
  3. Rename this directory.
  4. Set permissions on the Sugar files. The following directories, all subdirectories, and files must be writable by your web server user:
    • cache
    • custom
    • modules
    • config.php
    • config_override.php
    • sugarcrm.log
    Note: Typically, there are multiple versions of the log file, such as sugarcrm.log, sugarcrm.log.1, sugarcrm.log.2, and so on.
    For example:
    chgrp ApacheUser.ApacheGroup <SugarInstallRoot> -R recursively sets ownership for root directory to Apache user and group.
    chmod 755 <SugarInstallRoot> -R recursively sets permissions to Read/Write, Execute for the owner, and Read/Execute for everyone else.
    The system user that your web server uses to access files in your webroot varies depending on your operating system configuration. Common web server users include:
    • apache (Linux/Apache)
    • nobody (Linux/Apache)
    • IUSR_computerName (Windows/IIS)
    Consult your system administrator if you are unsure of your web server user.
  5. Ensure that file permissions are set for Read/Execute to includes directory and sugar root directory (in addition to the already existing list of directories/files) before you view Sugar on your browser.

Using the Sugar Setup Wizard

Use the Sugar Setup Wizard after copying the Sugar files into your web root. The Sugar Setup Wizard is located at

http://<yourServer>/<yourSugarDirectory>/install.php.

For example: http://localhost/Sugar-Full_6.5.0/install.php

You can perform a typical installation or a custom installation. Typical installation is recommended, but you can choose custom installation for the following reasons:

The same Database Admin User should not be used as the Sugar database administrator
Locale settings should be specified during installation instead of after logging into Sugar
To perform a typical installation of Sugar
1.
Launch your browser and enter the URL mentioned above.
This displays the Welcome page.
2.
Click Next.
The Installer displays installation instructions and requirements to help determine successful Sugar installation.
3.
Review the information and click Next.
This displays the Sugar License Agreement.
4.
Review the license, check I Accept, and click Next.
The installer checks the system for compatibility and then displays the Installation Options page.
Note:
You can modify any of your settings at any time prior to clicking Install in the Confirm Setting menu. To modify any settings, click the Back button on your browser to return to the appropriate page.
5.
Select Typical Install. Input the license key information in the Download Key field.You can also enter it after you have installed the application.
6.
Click Next.
This displays the Database Type page.
7.
Select the database that is installed on your system and click Next.
This displays the Database Configuration page.
a.
Enter the database name. The Installer uses sugarcrm as the default name for the database. You can specify a new name.
b.
Enter the Host Name or the Host Instance for My SQL and SQL Server.
The host name is, by default, set to localhostif your database server is running on the same machine as your web server.
c.
Enter the username and password for the Database Administrator and specify the Sugar Database Username.
d.
Ensure that the Database Administrator you specify has the permissions to create and write to the Sugar database.
For My SQL and SQL Server, by default, the Installer selects the Admin User as the Sugar Database User. The Sugar application uses Sugar Database User to communicate with the Sugar database. You can create a different Sugar Database user at this time.
To select an existing user, choose Provide existing user from the Sugar Database Username drop-down list. To create a new Sugar Database user, choose Define user. Enter the database username and password in the relevant fields. Re-enter the password to confirm it. The new user information is displayed in System Credentials on the Confirm Settingspage at the end of the installation process.
e.
Accept No as the default value if you do not want the Sugar Demo data. Select Yes to populate the database with the Sugar Demo data.
8.
Click Next.
The Installer validates the credentials of the specified administrator. If a database with that name already exists, it displays a dialog box asking you to either accept the database name or choose a new database. If you use an existing database name, the database tables will be dropped.
9.
Click Accept to accept the database name or click Cancel and enter a new name in the Database Name field.
This displays the Site Configuration page.
10.
Enter a name for the Sugar administrator.
The Sugar administrator (default name admin) has administrative privileges in Sugar. You can change the default username.
11.
Enter a password for the Sugar admin, re-enter it to confirm the password, and click Next.
This displays the Confirm Settings page. The Confirm Settings page displays a summary of the specified settings. Click Back on your browser to navigate to previous pages if you want to change the settings.
12.
Click Print Summary for a printout of the settings for your records.
Click Show Passwords and then click Print Summary to include the database user password and the Sugar admin password in the printout. When you click Show Passwords, the system displays the passwords and changes the button name to Hide Passwords. You can click this button to hide the passwords again.
13.
Click Install.
This displays the Perform Setup page with the installation progress.
14.
Click Next when the setup is complete.
This displays the Registration page. Registration is optional.
15.
Enter the necessary information and click Send Registration to register your Sugar instance with SugarCRM; or click No Thanks to skip registration.
This displays the Sugar login page. You can now log into Sugar with the Sugar admin name and password that you specified during installation.
To perform a custom installation of Sugar
1.
Launch the browser and enter the URL described above.
This displays the Welcome page.
2.
Click Next.
The Installer displays installation instructions and requirements to determine a successful Sugar installation.
3.
Review the information and click Next.
This displays the Sugar License Agreement page.
4.
Review the license, check I Accept, and click Next.
This displays the Installation Options page
5.
Select Custom Install and click Next.
This displays the Database Typepage.
6.
Select the database of your choice and click Next.
7.
Enter the database name.
The Installer displays sugarcrm as default name for the database. You can specify a new name for the database as well.
a.
Enter the Host Name or the Host Instance for My SQL and SQL Server.
The host name is set to localhost by default if your database server is running on the same machine as your web server.
b.
Enter the username and password for the Database Administrator and specify the Sugar Database Username.
Ensure that the Database Administrator you specify has the permissions to create and write to the Sugar database.
For My SQL and SQL Server, by default, the Installer selects the Admin User as the Sugar Database User. The Sugar application uses the Sugar Database User to communicate with the Sugar database. You can also create a different Sugar Database user.
Select Provide existing user from the Sugar Database Username drop-down list to select an existing user. Select Define user to create a new Sugar Database user. Enter the database username and password in the relevant fields. Re-enter the password to confirm it. This new user information displays in System Credentials on the Confirm Settings page at the end of the installation process.
c.
Accept No as the default value if you do not want the Sugar Demo data. Select Yes to populate the database with the Sugar Demo data.
8.
Click Next.
The Installer validates the credentials of the specified administrator. If a database with the specified name already exists, it displays a dialog box prompting you to either accept the database name or choose a new database. If you use an existing database name, the database tables will be dropped.
9.
Click Accept to drop current tables or click Cancel and specify a new database name.
10.
Click Next.
This displays the Site Configuration page.
11.
Enter the URL of your Sugar instance.
12.
Enter a name for your system to display on the Sugar application’s browser title bar.
13.
Enter a name for the Sugar administrator. The Sugar administrator (default name admin) has administrative privileges in Sugar. You can change the default name.
14.
Enter a password for the Sugar administrator, re-enter it to confirm the password, and click Next.
This displays the security options on the Site Security page.
15.
Select the desired security options and input information in the relevant fields.
16.
Click Next.
The Installer displays the Confirm Settings with a summary of the specified settings.
17.
Click Show Passwords and Print Summary to include the database user and the Sugar admin passwords in the printout.
18.
Click Install.
This displays the Perform Setup page with the installation progress.
19.
Click Next when the setup is complete.
This displays the Registration page. Registration is optional.
20.
Enter the necessary information and click Send Registration to register your Sugar instance with SugarCRM or click No Thanks to skip registration.
This displays the Sugar login page. You can now log into Sugar with the Admin user name and password specified during installation. You can set up Sugar during the login process, or you can set it up after you have logged in. For more information, see Accessing Sugar and setting your User Preferences.

Upgrading Sugar

For Sugar Ultimate, Sugar Enterprise, Sugar Corporate, and Sugar Professional, download the Upgrade zip file from the Sugar Support Portal at
http://www.support.sugarcrm.com into your local machine.

Log into the Sugar application to use the Upgrade Wizard. Run a PHP script from the command line on the server where the Sugar instance is installed to use the Silent Upgrader.

CAUTION:

It is strongly recommended that you run the upgrade process on a copy of your production system.

Compatibility matrix for upgrade

PHP version
5.2.1-5.2.6, 5.2.8-5.2.15, 5.2.17, 5.3.0 - 5.3.6
Databases
MySQL - 5.0x, 5.1
MSSQL - 2005, 2008
Operating systems
Windows: Sugar runs on any OS that runs PHP
Linux: Sugar runs on any OS that runs PHP
Mac: Sugar runs on any OS that runs PHP

Upgrade prerequisites

Backup your current Sugar directory and database before beginning the upgrade process.
Disable op-code caching before upgrading your Sugar installation if op-code caching is enabled in the PHP configuration file. You can enable it after the upgrade process is complete.
Increase the default value of the parameters listed below before you begin the upgrade process if you are using Zend Core 2.0:
¢
Navigate to C:\Program Files\Zend\Core\etc\fastcgi.conf and increase the default value for ConnectionTimeout to 3000 seconds and RequestTimeout to 6000 seconds.
¢
Navigate to the php.ini file and increase the default value of max_execution_time to 6000 seconds.
Perform the following for the large size of the upgrade files:
¢
Modify and save the value of Maximum upload size to 21000000 (20MB) in the Advanced section of the System Settings page of your current Sugar installation.
¢
Navigate to the php.ini file on your web server and configure the parameters listed below in the Advanced section of the System Settings page of your current Sugar installation:
l
Set post_max_size to at least 60MB
l
Set upload_max_filesize settings to at least 60MB
l
Set max_input_time to a large number
l
Set memory_limit to 256MB
Restart the web server and begin the upgrade process.
Ensure that LimitRequestBody is set to a large number or use the default value of 2GB if you are using an Apache web server and LimitRequestBody is set in the httpd.conffile. Restart Apache and begin the upgrade process.
Ensure that the webserver user has write permissions to the Sugar database. The upgrade to Sugar 6.5 will add and replace files in several locations including the Sugar root directory. The webserver usermust have write permissions for the root folder and all sub-directories during the upgrade process.
The process of upgrading can take up to 30 minutes. Set the CGI script timeout to more than the default 300 seconds to ensure that the CGI application does not time out if you are using the IIS web server.
Save PHP files for customized modules (for example, accounts.php) in the Customs directory and not within the main module. Existing customizations may be overridden by changes in Sugar 6.5 during upgrade.

Upgrade considerations

The Dynamic Teams feature requires some database schema changes across all modules as part of the upgrade process. For larger databases, this operation can take some time to complete. Follow the steps listed below to ensure a smooth upgrade process:

1.
Test your upgrade on a development instance instead of the production instance.
2.
Use the Silent Upgrade method through the command line interface to conduct the upgrade instead of the Upgrade Wizard inside the application if your database contains more than 10000 records per table.
3.
Log into the application as an Administrator and use the Repair option to repair and rebuild the database after the upgrade is complete.

Using the Upgrade Wizard

The Upgrade Wizard provides a quick way to upgrade to the latest version of the Sugar application. It includes critical upgrade logic as well as the SQL commands needed to upgrade the application.

Ensure that the config.php file for your installation, located in the Sugar root directory, is writable, before using the Upgrade Wizard.

Note:

Manual upgrades by file replacements and running the upgrade SQL are not supported.

To upgrade Sugar using the Upgrade Wizard
1.
Download the appropriate Sugar Upgrade zip file from the Sugar website to your local machine. For example, download the SugarPro-Upgrade-6.4.x-to-6.5.0.zipfile to upgrade Sugar Professional from version 6.4.x to 6.5.0. Download the appropriate conversion file to convert to Sugar Professional or Sugar Enterprise.
2.
Log into your existing Sugar application as the administrator and click admin on the right-hand corner of the page.
3.
Click Upgrade Wizard in the Systems panel of the Administration Home page.
This displays the Upgrade Wizard page.
4.
Click Next.
This displays the System Checks page. and Sugar begins the system check process. The Systems Check page indicates that there were no issues if the system check process completes successfully. Issues with file permissions, database, and server settings are listed on the page if the system check process encountered any problems.
5.
Click Next if the system check is successful.
This displays the Upload an Upgrade page.
6.
Click Browse, and navigate to the location of the upgrade zip file and select it.
The path to the file displays in the Upload an upgrade field.
7.
Click Upload Upgrade to upload the package to the Sugar application.
The system uploads the package and displays it on the page. Use the Delete Package button to remove the package if necessary.
8.
Click Next.
This displays the Preflight Check page.
Click Show Schema Change Script toview differences in the Sugar databases schema between your current and new Sugar versions.
By default, the Upgrade Wizard Runs SQL option is selected as the database update method. Select Manual SQL Queries from the Database Update Method drop-down list and select the Check when SQL has been manually run box, if you ran the SQL queries manually.
9.
Click Recheck to rerun Preflight Check. Click Next to skip this step.
This displays the Commit Upgrade page.
You can also click Show to see a list of files that were copied and the rebuilt results. You can also view skipped queries.
10.
Click Next.
During the upgrade process, Sugar performs a three-way merge between the customized instance on old version, default instance on old version, and default instance on new version. This three-way merge adds any fields that have been added to the default module layouts in the new version to the corresponding module layouts in the existing version, if the module layouts in the old version were not customized through Studio (or in the appropriate upgrade-safe way) prior to the upgrade. The three-way merge also changes the placement of fields in non-Studio-customized module layouts to match the placement in the default module layouts.
Sugar displays the Confirm Layouts page as Step 5 of the upgrade process if the existing module layouts have been customized, and there are changes to the default fields and field placement in the new module layouts.
The Confirm Layouts page lists the module layouts that have changed in the new version. The administrator has the option of applying the changes to the existing module layouts. By default, all of the listed module layouts are selected to be merged during the upgrade.
For example, in 6.1.0, Sugar added the Assigned To fields to the default Detail View and Edit View layouts for Notes and for Email Templates. If the instance being upgraded has a customized EditView layout for Notes, but no customized layouts for Email Templates, the following will occur during the upgrade:
a.
The Confirm Layouts page appears as Step 5 in the Upgrade Wizard
b.
The Confirm Layouts page displays the Notes module with the EditView and DetailView layouts. The Email Templates layouts do not display on the Confirm Layouts page because the existing layouts were not customized.
c.
The Administrator has the option of choosing to merge the changes in the Notes module with the existing customized EditView layout.
11.
Uncheck the module if you do not want to add the new fields to a module.
12.
Click Next.
This displays a message confirming that the layouts were successfully merged (if you chose to update your modules).
13.
Click Next.
14.
The Debrief page confirms the upgrade installation. Complete the steps for manual merging of files or running SQL queries now.
15.
Click Done.
This displays the Home page indicating that the upgrade is complete.
16.
Click Repair and select the Rebuild Relationships andRebuild Extensions options in the Systems panel of the Administration Home page.
For more information, see Repair.
17.
Manually merge the files by extracting the skipped file from the patch zip file if you unchecked any files to prevent the Upgrade Wizard from overwriting them. Merge the file installed in the Sugar application directory.
Note:
Check the upgradeWizard.log file in the Sugar folder for information on unsuccessful Sugar upgrades.

Locking down the Upgrade Wizard

You can lock down the Upgrade Wizard to ensure that no user with administrative privileges can upgrade any of them, if you are managing multiple instances of the Sugar application and you want to maintain complete control over the Sugar instances. Follow the steps listed below to lock down functions on the Administration page:

1.
Navigate to the config.php file in the Sugar root directory.
2.
Set the following parameter to true as below:
$sugar_config[’admin_access_control’]=true
3.
Save the file.

Converting Sugar Editions

The Upgrade Wizard enables you to convert from one Sugar edition to another. Obtain the Sugar license key from your sales representative for the Sugar edition you want.

The table below lists the supported conversions.

Sugar Edition
Supported Conversion
Sugar Community Edition versions 6.1.x, 6.2.x, 6.3.x, 6.5.x
Sugar Ultimate 6.5.0
Sugar Enterprise 6.5.0
Sugar Corporate 6.5.0
Sugar Professional 6.5.0
Sugar Professional versions 6.1.x, 6.2.x, 6.3.x, 6.4.x
Sugar Ultimate 6.5.0
Sugar Enterprise 6.5.0
Sugar Corporate 6.5.0
Sugar Corporate versions 6.2.x, 6.3.x, 6.4.x
Sugar Ultimate 6.5.0
Sugar Enterprise 6.5.0
Sugar Enterprise versions 6.1.x, 6.2.x, 6.3.x, 6.4.x
Sugar Ultimate 6.5.0

You will need to obtain the Sugar license key from your sales representative for the Sugar edition you want.

Conversions are a two-step process. First you must upgrade your existing Sugar application from the current version to 6.5.0. You can then convert to the desired Sugar edition using the appropriate conversion zip file.

For example, to move from Sugar Community Edition 6.4.1 to Sugar Professional 6.5.0, you must first convert to Community Edition 6.5.0 using the 6.4.x-to-6.5.0.zip file. You can then convert from Community Edition 6.5.0 to Professional 6.5.0 using the SugarCE-to-SugarPro-Conversion-6.5.0.zip file.

Using the Sugar Silent Upgrader

The Silent Upgrader enables you to avoid some of the limitations that the web application environment may have that prevents the Upgrade Wizard from completing the upgrade. The upload size limit (by PHP and sometimes even by web server), the CGI (or equivalent) timeout limit, and the MySQL (or equivalent) session timeout limit are some of the challenges people run into when upgrading Sugar. The Silent Upgrader either avoids the limitations or better controls the settings in its stand-alone execution environment.

Note:

The silentUpgrade.php script creates new files for the user. For example, for the root user it create 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.

To upgrade Sugar using the Silent Upgrader
1.
Execute the silentupgrade.php script from the command line on the server where the Sugar instance is installed:
php.exe -f silentUpgrade.php [upgradeZipFile] [logFile ][pathToSugarInstance] [adminUser ]
where:
upgradeZipFile is the full path to the upgrade zip file. For example, SugarCE-Upgrade-6.2.0-to-6.5.0.zip
logFile is the full path to the log file.
pathToSugarInstance is the full path to the instance being upgraded.
adminUser is a valid admin user name.
2.
Log into the Sugar application as the administrator and rebuild relationships and extensions using the Repair option in the Systems sub-panel after upgrading.

Uninstalling a Sugar instance

Follow the steps listed below to uninstall your Sugar instance:

1.
Navigate to the location where Sugar is installed on your machine and delete the Sugar root directory.
2.
Delete the Sugar database schema from the MySQL or MS SQL server database.

Copyright 2004-2011 SugarCRM Inc.
Community Edition License

Last Modified:29 Oct 2014 08:59