Migrating From SugarCloud to On-Site

Overview

Occasionally, system administrators will have the need to deploy versions of their instance hosted on Sugar's cloud service to an on-site system. Reasons for this type of deployment are:

Testing locally-developed modules
Migrating from SugarCloud to on-site

Prerequisites

Before migrating Sugar to an on-site environment, you will need to request a backup of your SugarCloud system by filing a case with the Sugar Support team. Once the backup request is received, SugarCRM will provide an FTP account where the following files can be downloaded:
- instance_name-YYYYMMDDHHmm.sql.gz (backup of database)
- instance_name-YYYYMMDDHHmm-triggers.sql.gz (backup of database triggers)
- instance_name-YYYYMMDDHHmm.files.tgz (backup of file system)
The local system must be running MySQL. Converting the database to another system, such as SQL Server or Oracle, requires special handling. For more information regarding this type of conversion, please contact your Account Manager.
On-site system administrators must be familiar with their stack and the tools (gunzip, tar, mysqladmin, mysql, etc.) referenced in this guide.

Note: It is the system administrator's responsibility to diagnose and troubleshoot issues specific to the stack (permissions, environment variables, etc.).

Steps to Complete

Deploy the backup files to a local system using the following steps:

Extract and import the SQL data as follows:
- Extract the SQL file via an archive utility (e.g. 7-Zip) or via command line such as:
```
gunzip instance_name-YYYYMMDDHHmm.sql.gz
```
- Create a database on your MySQL server via command line:
```
mysqladmin -u mysql_username -p create instance_name
```
  Or, if already logged into MySQL, with a command such as:
```
CREATE DATABASE instance_name;
```
- Import the SQL data to your MySQL server via the command line:
```
mysql -u mysql_username database_name -p < instance_name-YYYYMMDDHHmm.sql
```
- Extract the Triggers file via an archive utility (e.g. 7-Zip) or via command line such as:
```
gunzip instance_name-YYYYMMDDHHmm.triggers.sql.gz
```
- Import the Triggers data to your MySQL server via the command line:
```
mysql -u mysql_username database_name -p < instance_name-YYYYMMDDHHmm.triggers.sql
```
Extract the tar file to your web server's web root directory (e.g. /var/www/html) with the following command:
```
tar -C /var/www/html -xzf instance_name-YYYYMMDDHHmm.files.tgz
```
This will create a directory named "instance_name-YYYYMMDDHHmm" in your web root directory.

Rename the newly created directory:

mv /var/www/html/instance_name-YYYYMMDDHHmm /var/www/html/instance_name

For Linux-based servers, perform the following actions:
- Change the ownership of the directory to be accessible by the Apache user and group. Please note that the user and group (e.g. apache, www-data, etc.) values can vary depending on your web server configuration.
```
chown -R apache:apache /var/www/html/instance_name
```
- Change the permissions of the directory to ensure files can be accessed by the application. The actual permission values may differ depending on server security settings.
```
chmod -R 770 /var/www/html/instance_name
```

Edit the ./config.php file to point to your database.

Open the ./config.php file:

vi /var/www/html/instance_name/config.php

Locate and update the dbconfig array with the information appropriate for your MySQL server as follows:

'dbconfig' => array (
	'db_host_name' => 'localhost',
	'db_host_instance' => 'SQLEXPRESS',
	'db_user_name' => 'mysql_username',
	'db_password' => 'mysql_password',
	'db_name' => 'instance_name',
	'db_type' => 'mysql',
	'db_port' => '',
	'db_manager' => 'MysqliManager',
),

Edit the config.php file and modify the following parameters:
- site_url should be the URL of the instance on your server (e.g. https://www.mysugarinstance.com)
- host_name should be the URL of the instance without the https protocol (e.g. www.mysugarinstance.com)
Modify the .htaccess file in the root directory of the instance.
- Remove the following lines if they exist in the file:
```
#Added by operations to force SSL
RewriteEngine On
RewriteCond %{QUERY_STRING} !^entryPoint=WebToLeadCapture
RewriteCond %{HTTP:X-SSL-CLUSTER} !^od2$
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L]
```
- If your on-site deployment does not reside in the root of your domain (e.g. https://www.example.com/mysugar/), change the following line from:
```
RewriteBase /
```
  to:
```
RewriteBase /mysugar/
```
If you are migrating permanently to an on-site deployment, there are additional modifications that should be made to ensure full functionality for your instance of Sugar.
- To restore the ability to perform upgrades, open the ./config.php file and remove the following line:
```
'disable_uw_upload' => true,
```
- To display the full-text search configuration options under Admin > Search, open the ./config.php file and remove the following line:
```
'hide_full_text_engine_config' => true,
```
- To display the Sugar log settings under Admin > System Settings, open the ./config.php file and remove the following line:
```
'logger_visible' => false,
```
- To bypass security checks when installing packages via Admin > Module Loader, open the ./config.php file and change the following line from:
```
'packageScan' => true,
```
  to:
```
'packageScan' => false,
```
- To ensure full-text search functions properly, open the ./config.php file and modify the following lines to point to your ElasticSearch configuration:
```
'full_text_engine' => array (
	 'Elastic' => array (
		 'host' => '<your_elastic_search_host>',
		 'port' => '<your_elastic_search_port>',
	 ),
 ),
```
Disable the SugarCloud Insights service as this is only available for SugarCloud instances. Open the ./config.php file and change 'enabled' => true, to 'enabled' => false, in the following array:
```
'cloud_insight' => 
  array (
    'enabled' => true,
    'url' => 'https://sugarcloud-insights.service.sugarcrm.com',
    'key' => '<insights key>',
  ),
```
Finally, please navigate to Admin > Repair and perform a "Quick Repair and Rebuild" to clear all cached elements from the SugarCloud instance.

You should now have a working version of your SugarCloud instance accessible from your local server.