empty
| 
Sugar Community Edition 5.5 Documentation
Sugar Community Edition Application Guide
Version 5.5.0
|
|
|
|
Installing and Upgrading Sugar
Installing and Upgrading Sugar
This chapter 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.
Before installing Sugar 5.5.0, ensure that you have the appropriate components installed on your server. See the Sugar Community Edition Release Notes for a complete list of the supported software versions.
|
Note:
|
|
•
|
If you are using MySQL, install version 5.0 or higher to use with Sugar 5.5.0.
|
|
•
|
If you are using Microsoft SQL Server, you need to download the SQL Server Driver for PHP from Microsoft and extract the contents to the /ext directory of the PHP installation. Then add the following line in php.ini to enable it:
|
The driver also requires you to install the Microsoft SQL Server Native Client on the web server. Install the version for SQL Server 2005 even if you are installing on SQL Server 2008.
In order to better support multi-byte character storage with Microsoft SQL Server, you can configure Sugar to use the FreeTDS driver.
If you have already installed Sugar version 5.5.0, then you will need to migrate the application to use the FreeTDS driver. A pre-requisite for migration is that you are using Sugar version 5.5.0 with SQL Server 2005 on Apache with a PHP version 5.2.0 or higher. This means that your current php.ini file and config.php file for SugarCRM instance should already reflect the necessary changes to run SugarCRM with SQL Server. The assumption is that there is data in the tables with multi-byte character values. You can also choose to create test data from a new 5.5.0 instance. This can be setup through the installation process by choosing to populate multi-byte character seed data with the installer. For more information, see “To migrate Sugar to FreeTDS driver”.
|
1.
|
Navigate to http://www.sugarforge.org/frs/?group_id=6.
|
|
2.
|
Download the sugarcrm MB mssql.zip file listed under Sugar CE 5.5/MSSQL MB Driver.
|
|
3.
|
Ensure that Sugar is installed on Apache and that you can connect to SQL Server Database V. 2005 from it.
|
|
4.
|
Backup the original php.ini file and save it at a location from where you can retrieve it if the changes render Apache inoperable.
|
|
5.
|
Modify your php.ini file to include extension for FreeTDS and comment out the existing php_mssql.dll extension as shown below.
|
|
6.
|
Change the mssql.charset value to utf-8. If the mssql.charset parameter is missing, add it underneath the default_charset setting as shown below.
|
|
7.
|
Open the sugarcrm MB mssql.zip file and do the following:
|
|
a.
|
Copy the appropriate php_dblib.dll to the extensions folder of the PHP installation.
|
There are three separate folders for three different versions of PHP (5.1.x, 5.2.x, 6.x). The php_dblib.dll file is the FreeTDS dynamic link library file. Your extension directory is the value for the extension_dir key in the php.ini file. Typically, it is located in the ext folder. Ensure that you choose the appropriate version of the FreeTDS dynamic link library to use. They are organized according to PHP versions under the Drivers folder.
|
b.
|
Place the freetds.conf file in the c:\ directory of your Windows operating system.
|
If the SQL Server instance is listening to connections on a port other than the default (1433), modify the freetds.conf file accordingly. Even if your Program Files folder that runs SQL Server or Apache resides in another directory (for example, in d: or e:), the freetds.conf file should still go in the c:\ directory.
|
c.
|
Copy ntwdblib.dll and msvcr71.dll to the Windows/SYSTEM32 folder for runtime extension support and verify the accuracy of the ntwdblib.dll file.
|
The msvcr71.dll file is also included in the freetds.zip file and should be copied into the Windows/SYSTEM32 folder as well. The subdirectories of your Apache installation directory may also contain copies of the ntwdblib.dll file. Ensure that the versions of the ntwdblib.dll file in those folders match the one you have placed in Windows/SYSTEM32. If you are unsure, you may also rename the ntwdblib.dll files under the Apache directories to be safe.
|
9.
|
From the command line where the apache.exe file resides enter the following command from a DOS or SHELL terminal:
|
Alternatively, use any Apache management tools that you are familiar with to restart the Apache Web server.
If you have problems connecting to the SQL Server database Express edition during the database configuration installation process, do the following:
|
•
|
Try alternating the use of the IP Address of the host name with and without an explicit port number. For example:
|
|
1.
|
Backup the Sugar database using tools such as the MS SQL Server Management Studio application.
|
|
c.
|
Select the database you want to copy (Tasks->Copy Database). This will take you to a wizard application that will complete the process of making a backup of the existing database.
|
|
2.
|
Run the upgrade_mssql.php script in the root directory of the Sugar installation.
|
Run this file through the Command Line Interface. Ensure that your PATH settings are setup properly to allow for PHP command line execution. Your PHP executable may reference another php.ini file.
If so, check to make sure that the php.ini file used by the command line PHP executable also has the php_mssql.dll extension enabled. Run the command as follows:
|
4.
|
Follow the steps outlined in “To enable Sugar for FreeTDS driver” starting from modifying your php.ini file as detailed in Step 5.
|
To ensure your Sugar installation is secure from unauthorized access, 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 the httpd.conf file. After you install Sugar, a .htaccess file is created in your Sugar installation directory. This file contains the following content:
RedirectMatch 403 (?i)/+(soap|cache|xtemplate|data|examples|include|log4php|metadata|modules)/+.*\.(php|tpl)
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.
For IIS, you must create rules that specify the conditions to prevent unauthorized access as follows:
|
2.
|
Select the URL Rewrite option.
|
|
3.
|
|
4.
|
Ensure that you specify Regular Expressions in the Using field and Send 403 (Forbidden) response in the How to block field.
|
|
a.
|
|
Note:
|
Sugar creates a web.config file for IIS 7 during the installation process. This file performs the same function as the .htaccess file. To ensure that web.config is functioning correctly, attempt to access the sugarcrm.log file through the browser. If you can access the log file, perform the procedure described above to prevent unauthorized access to your Sugar installation.
|
Installing Sugar
|
3.
|
Install Sugar Community Edition with the Sugar Setup Wizard.
|
|
2.
|
Navigate to Support & Training/Support Portal or visit http://www.sugarcrm.com/sugarshop/downloads.php.
|
|
5.
|
On the Download Manager page, enter your download key into Download Key field and click Submit.
|
|
6.
|
|
1.
|
Locate your webroot directory on your Web server. This is the directory on your web server where publicly accessible files are made available by your Web server. Common locations for Web root includes:
|
/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)
|
4.
|
Set permissions on the Sugar files. The following directories, all subdirectories, and files must be writable by your Web server user:
|
|
•
|
|
•
|
|
•
|
|
•
|
"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:
|
5.
|
Prior to viewing Sugar through the browser, 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).
|
After you copy the Sugar files into your web root, you can use the Sugar Setup Wizard. The Sugar URL http://<yourServer>/<yourSugarDirectory>/install.php is the URL that you will use to access the Sugar Setup Wizard.
For example: http://localhost/Sugar-Full_5.5.0/install.php
You can perform a typical installation or a custom installation. While typical installation is recommended, you can choose custom installation for the following reasons:
|
•
|
You want to specify the locale settings during installation instead of specifying it after you log into the Sugar application.
|
The Welcome page displays on the screen. This screen lists the requirements to help determine if you can successfully install Sugar. Read this page before proceeding with the installation.
|
2.
|
Click Next.
|
The Installer displays the Sugar License Agreement screen.
The installer checks the system for compatibility and then displays the Installation Options screen.
|
Note:
|
At any time prior to clicking Install in the Confirm Setting menu, you can modify any of your settings. To modify any settings, click the Back button to get back to the appropriate screen.
|
|
4.
|
The Database Type screen displays next.
|
5.
|
Select the database that is installed on your system and click Next.
|
|
6.
|
Enter the database name. The Installer displays sugarcrm as the default name for the database, but you can specify a new name for the database.
|
If your database server is running on the same machine as your Web server, the host name is, by default, set to localhost.
|
8.
|
Enter the username and password for the Database Administrator. Then, 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. But, at this time, you can create a different Sugar Database user.
To select an existing user, select Provide existing user from the Sugar Database Username drop-down list. To create a new Sugar Database user, select Define user to create. Enter the database user name and password in the fields that display below. Reenter the password to confirm it. This new user information will display under “System Credentials” on the Confirm Settings page at the end of the installation process.
|
9.
|
From the Demo Data drop-down list, select Yes to specify that you want to populate the database with the Sugar Demo data. Or else, select No.
|
|
10.
|
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 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.
|
11.
|
Click Accept to accept the database or else click Cancel and enter a new name in the Database Name field.
|
The Site Configuration screen displays on the page.
|
12.
|
The Installer displays the Locale Settings screen which lists the default settings for your locale.
|
14.
|
Click Next.
|
The Installer displays the Confirm Settings screen. This screen displays a summary of the settings that you specified.
|
15.
|
If you want a printout for your records, click Print Summary.
|
To include the database user password and the Sugar admin password in the printout, click Show Passwords and then click Print Summary. 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.
|
16.
|
The Perform Setup page displays the installation progress on the screen.
|
17.
|
|
19.
|
To register your Sugar instance with SugarCRM, enter the necessary information and click Send Registration; or else click No Thanks to skip registration.
|
The Sugar log-in page displays on the screen. You can now log into Sugar with the username and password that you specified during installation.
The Welcome page displays on the screen. This screen lists the requirements to help determine if you can successfully install Sugar. Read this page before proceeding with the installation.
|
2.
|
Click Next.
|
The installers checks the system for compatibility and then displays the Installation Options screen
The Installer displays the Database Type screen.
|
4.
|
Select the database of your choice and click Next.
|
|
5.
|
Enter the database name.
|
The Installer displays sugarcrm as default name for the database, but you can specify a new name for the database.
If your database server is running on the same machine as your Web server, the host name is, by default, set to localhost.
|
7.
|
Enter the username and password for the Database Administrator. Then, 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. But, at this time, you can create a different Sugar Database user.
To select an existing user, select Provide existing user from the Sugar Database Username drop-down list. To create a new Sugar Database user, select Define user to create. Enter the database user name and password in the fields that display below. Reenter the password to confirm it. This new user information will display under “System Credentials” on the Confirm Settings page at the end of the installation process.
|
8.
|
Select Yes from the Demo Data drop-down list to specify that you want to populate the database with the Sugar Demo data. Or else, accept No as the default value.
|
|
9.
|
Click Next.
|
|
10.
|
|
11.
|
Click Next.
|
|
13.
|
Enter a name for your system to display to users on the Sugar application’s browser title bar.
|
|
14.
|
|
15.
|
Select the security options of your choice and specify the necessary information in the appropriate fields.
|
|
16.
|
Click Next.
|
The Installer displays the Confirm Settings screen. This screen displays a summary of the settings that you specified.
|
18.
|
To include the database user password and the Sugar admin password in the printout, click Show Passwords and then click Print Summary.
|
|
19.
|
The Perform Setup page displays the installation progress on the screen.
|
20.
|
|
21.
|
The Installer displays the Registration page on the screen.
|
|
22.
|
To register your Sugar instance with SugarCRM, enter the necessary information and click Send Registration; or else click No Thanks to skip registration.
|
The Sugar log-in page displays on the screen. You can now log into Sugar with the Admin username and password that you specified during installation.
This section describes how to upgrade from Sugar Enterprise, Sugar Professional, and Sugar Community Edition 5.1.0 and 5.2.0 to version 5.5.0 using the Upgrade Wizard or the Silent Upgrader. You can also upgrade from Sugar Express 5.2.0d to 5.5.0.
In order to upgrade your Sugar application, you need to download the appropriate Upgrade.zip file from the Sugar website to your local machine. For Sugar Enterprise, Sugar Professional, and Sugar Express you can obtain the Upgrade zip file from the Sugar Support Portal at https://www.sugarcrm.com/crm/support and upload it to your local machine. For Sugar Community Edition, you can upload the Upgrade zip file from the SugarCRM website to your local machine.
To use the Upgrade Wizard, you need to log into the Sugar application. To use the Silent Upgrader, you need to run a PHP script from the command line on the server where the Sugar instance is installed.
|
CAUTION:
|
It is strongly recommended that you run the upgrade process on a copy of your production system.
|
|
5.2.1-5.2.6, 5.2.8-5.2.11
|
|
|
MySQL - 5.0x, 5.1
MSSQL - 2005, 2008
Oracle - 9i, 10g
(Oracle is supported only for Sugar Enterprise)
|
|
|
Windows: XP, 2003, 2008, Vista,
Linux: Red Hat 4.x, 5.x (Advanced Server, Enterprise Server); Oracle Enterprise Linux 5.1; CentOS 4.x, 5.x
|
|
•
|
If op-code caching is enabled in the PHP configuration file, you will need to disable it before upgrading your Sugar installation. You can enable it after the upgrade process is complete.
|
|
•
|
If you are using Zend Core 2.0, you will need to increase the default value of the parameters listed below before you begin the upgrade process:
|
|
•
|
Navigate to C:\Program Files\Zend\Core\etc\fastcgi.conf and increase the default value for ConnectionTimeout to 3000 and RequestTimeout to 6000.
|
|
•
|
|
•
|
In the Advanced section of the System Settings page of your current Sugar installation, modify and save the value of Maximum upload size to 21000000 (20MB).
|
|
•
|
Navigate to the php.ini file on your Web Server and configure the parameters listed below as follows:
|
|
•
|
Set post_max_size to more than 20MB.
|
|
•
|
Set upload_max_filesize settings to more than 20MB.
|
|
•
|
Set max_input_time to a large number.
|
|
•
|
If you are using an Apache Web Server and if you have set LimitRequestBody in the httpd.conf file, then ensure that you set it to a large number or use the default value of 2GB. Restart Apache and then begin the upgrade process.
|
|
•
|
Ensure that the Webserver user has Write permissions to the Sugar database. The upgrade to Sugar 5.5.0 will add and replace files in several locations including the Sugar root directory. The Webserver user must 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. If you are using the IIS Web server, ensure that the CGI application does not time out. To do this, on IIS, set the CGI script timeout to more than 300 seconds, which is the default value.
|
|
•
|
If you have customized any module’s PHP file, for example, accounts.php, it is strongly recommended that you save it in the Customs directory and not within the main module. This is because, during upgrade, existing customizations may be overridden by changes in Sugar 5.5.0.
|
You can convert from one Sugar edition to another using the Upgrade Wizard. The table below lists the supported conversions.
Conversions are a two-step process. First you must upgrade your Sugar application from the current version to 5.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 5.2.0 to Sugar Enterprise 5.5.0, you must first convert to Community Edition 5.5.0 using the SugarCE-Upgrade-5.2.0-to-5.5.0.zip file. You can then convert from Community Edition 5.5.0 to Enterprise 5.5.0 using the SugarCE-to-SugarEnt-Conversion-5.5.0.zip file.
The Upgrade Wizard provides a quick way to upgrade to the latest version of the Sugar application. The Upgrade Wizard includes critical upgrade logic as well as the SQL commands needed to upgrade the application.
Before using the Upgrade Wizard, ensure that the config.php file for your installation is writable.
|
Note:
|
Attempting to manually upgrade by simply replacing files and running the upgrade SQL is not supported.
|
|
1.
|
Download the appropriate Sugar Upgrade zip file from the Sugar Website to your local machine. For example, to upgrade Sugar Professional from version 5.2.0 to 5.5.0, download the SugarPro-Upgrade-5.2.0-to-5.5.0.zip file.
|
|
2.
|
Log into your existing Sugar application as the administrator and click admin on the right-hand corner of the page.
|
|
3.
|
The Upgrade Wizard screen displays on the page.
|
4.
|
Click Next.
|
The System Checks page displays on the screen, and Sugar begins the system check process. If the process completes successfully, the page indicates that there were no issues. If not, any issues with file permissions, database, and server settings are listed on the page.
The Upload an Upgrade screen displays on the page.
|
6.
|
Click Browse, and navigate to the location of the upgrade zip file to select it.
|
The path to the file displays in the Upload an upgrade field.
|
7.
|
The system uploads the package and displays it on the page. The page also displays a Delete Package button that you can use to remove the package if necessary.
|
8.
|
Click Next.
|
The Preflight Check screen displays on the page.
You can view differences in the Sugar databases schema between your current Sugar version and the new Sugar version when you click Show Schema Change Script.
By default, the Upgrade Wizard Runs SQL option is selected as the database update method. If you ran the SQL queries manually, select Manual SQL Queries from the Database Update Method drop-down list and select the Check when SQL has been manually run box.
|
9.
|
The Commit Upgrade screen displays on the page.
Optionally, you can click Show to see a list of files that were copied and the rebuilt results. You can also view skipped queries.
|
10.
|
Click Next.
|
The Debrief screen confirms that the upgrade has been installed. If you had chosen to manually merge files or run SQL queries, you will need to complete those steps now.
|
11.
|
Click Done.
|
|
12.
|
In the Systems panel of the Administration Home page, click Repair and select the Rebuild Relationships and Rebuild Extensions options to perform these actions.
|
|
13.
|
If you unchecked any files to prevent the Upgrade Wizard from overwriting them, then manually merge the files by extracting the skipped file from the patch zip file. Merge the file that was installed in the Sugar application directory.
|
|
Note:
|
If your attempt to upgrade Sugar is unsuccessful, check the upgradeWizard.log file in the Sugar folder for information.
|
If you are managing multiple instances of the Sugar application and you want to maintain complete control over the Sugar instances, you can lock down the Upgrade Wizard to ensure that no user with administrative privileges can upgrade any of them. 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:
|
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 who is running it. For example, for the root user it create files as user/group root. Because Apache cannot read this, you must ensure that the Web server user has the permissions to read and write the script.
|
|
1.
|
From the command line on the server where the Sugar instance is installed, execute the silentupgrade.php script as follows:
|
upgradeZipFile is the full path to the upgrade zip file. For example, SugarCE-Upgrade-5.2.0-to-5.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.
|
After upgrading, log into the Sugar application as the administrator and rebuild relationships and extensions using the Repair option in the Systems sub-panel.
|
|
|
|
|
|
Copyright 2004-2009 SugarCRM Inc.
Community Edition License
