Migrating From SugarCloud to On-Site

Overview

This article will go through the process of migrating an instance on Sugar's cloud service to an on-site environment.

Please note that, if your current version of Sugar is classified as a "cloud-only" release, the instance is supported in Sugar's cloud environment only. Running a cloud-only version outside of Sugar's hosted environment as a production instance is not supported.

Prerequisites

Before migrating Sugar to an on-site environment, you will need to request a backup of your SugarCloud system as described in the Downloading Backups for SugarCloud Instances article. Once the backup has been downloaded and unzipped, it will contain the following files, which will be labeled with the version and product of Sugar that you are using (e.g. sugar711ent):
- sugarversionedition.sql (backup of database)
- sugarversionedition_triggers.sql (backup of database triggers)
- sugarversionedition (backup of file system)
Ensure that your on-site stack components are all supported for your Sugar version. For more information, please refer to the Supported Platforms page.
The local system must be running MySQL. It is recommended that you run MySQL version 5.7 to match Sugar's cloud environment.
Note: When running MySQL version 5.7, you must disable the ONLY_FULL_GROUP_BY setting to avoid potential errors in Sugar.
On-site system administrators must be familiar with their stack and the tools (gunzip, tar, mysqladmin, mysql, etc.) referenced in this article.

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 the backup file to your web server's web root directory (e.g., /var/www/html).
Create a database on your MySQL server via command line, replacing "instance_name" with what you would like to call your Sugar installation:
```
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 < sugarversionedition.sql

Import the triggers data to your MySQL server via the command line:

mysql -u mysql_username database_name -p < sugarversionedition_triggers.sql

Rename the directory containing the full filesystem of your Sugar instance:
```
mv /var/www/html/sugarversionedition /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)
You will need to create an .htaccess file if you do not have one from a previous Sugar installation. You can download a sample one here. Rename the file and place it in the root directory of the instance.
- 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 (opposed to creating a local testing environment), perform these additional modifications to ensure full functionality.
- 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>',
  ),

Disable the SugarIdentity service by running the following SQL query in your database, as this is only available for SugarCloud instances.
Note: If you wish to enable SugarIdentity for your on-site instance, you will need to go through the steps covered in the SugarIdentity Activation Guide for On-Site Instances.
```
DELETE FROM config WHERE category = "idm_mode"; 
```
When emails are archived to SugarCloud instances, they are automatically compressed to reduce the amount of database storage consumed in the instance.However, the decompression functionality, governed by the Email::supportsGzip method in modules/Emails/Email.php, fails to decompress the email data for on-site instances after migrating from SugarCloud.If you wish to decompress the email description and description_html fields, execute the following command from the root of your Sugar instance:
- php bin/sugarcrm email:process
Finally, please log into Sugar as an administrator and 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.