Cloning a Sugar Instance for Testing

Overview

A clone of your instance should always be created if you wish to test a change without risking your Sugar data or installation. This article will cover the three basic steps involved in cloning your instance:

1. Gather the code and data from your production instance.
2. Install the code and data from your production instance to a new location.
3. Adjust the new (cloned) code and data to be an autonomous instance.

Mastering the cloning process also enables you to make and restore backups of your production instance, which is useful outside of cloning.

Note: This article pertains to on-site installations of Sugar. For information about cloud sandboxes, please refer to the SugarCloud Sandboxes article.

Steps to Complete

Gathering the Code and Data From the Production Instance

A standard installation of Sugar has two parts to it:

• Code : The PHP, JavaScript, and other files that tell the server what to do when a request comes in from a user. The code is kept on your web server in the root direction of your Sugar application.
• Data : The information about your customers as well as metadata about your SugarCRM instance. The data is kept in a database (e.g. MySQL, MSSQL, Oracle).

Copying The Code

To copy the code, simply use whatever tool you use for file management to copy all of the files from the application root directory to another directory that is outside the application root directory. For example, if your application root directory is located at /var/www/sugarcrm, you can copy it to another directory such as ./username/documents/sugarcrm. You can also copy the files to a single archive file (e.g. zip, tar, etc.).

Note: Make sure to copy ALL files including hidden files. There are files like .htaccess that are very important to the correct working of Sugar.

Copying The Data

To copy the data from your instance, you'll need to use the standard backup procedure for the database system you use. Since most Sugar instances use MySQL, we'll use that database system as an example.

First, identify the database name your instance is using. To do so, open the file config.php, which you can find in the application root of either the production instance or the file backup you just made. In that file, do a search for the string db_name. You should find it paired with a value. For example, an entry such as 'db_name' => 'sugarcrm' indicates that the database name is "sugarcrm".

If you have root or administrative credentials, you will use them to access the database. If not, you will also need to gather the database username and password from the config.php file:

  'db_user_name' => 'myusername',
'db_password' => 'mypassword',

Though some databases like MSSQL have their own user interface-driven backup and restore systems, some like MySQL rely on a command line system like MySQLDump. Knowing the database name, the username, and the password, you can use a tool like MySQLDump to make a backup of the entire database and save it to a single file. In our case, we will use this at the command prompt on the database server: 

  mysqldump -u myusername -pmypassword sugarcrm > sugarcrm-backup.sql

The above command should be modified for your instance's values as follows:

  mysqldump -u [database user name] -p[database user password] [database name] > [file name and location where the copy of the data will be stored]

Note: There is no space between the "-p" and the password value. If you put a space between the -p and the password string, the password will not be properly recognized and the process will not work. 

MySQLDump will go through the entire database and create a script that, if run on a database, will recreate the entire contents of your instance. For more information about the options available for MySQLDump, please refer to this documentation on the MySQL site.

Once you have completed copying the code and dumping the data you have completed this first of three steps in the process. The combination of the archive file (zip) and the MySQLDump file you just created can also serve as a complete backup of your instance.

Installing the Code and Data to a New Location

Now that you have copied your site, place it somewhere else to work with it. Ideally, your cloned instance should be hosted in an exact copy of your production instance's environment. This is really easy to do if your production instance of Sugar is hosted from a directory off a website (e.g. https://www.yourwebsite.com/sugarcrm).

If this is the case, you can simply create a folder off of the website's root called something like "/sugardev". The new URL will look like this: https://www.yourwebsite.com/sugardev

If you are not sure how to set up a new environment, ask your web server administrator. Setting up your environment is outside the scope of this article. For the rest of this exercise, though, we will assume this is the setup you are using.

Just as there were two parts we needed to gather earlier to create the backup or copy of your instance, we will install the code and the data as two steps, which are covered in the next two sections.

Restoring the Code to a New Location

Restoring the code to a new location is just a matter of pasting a copy of the entire file structure you copied earlier into the directory within your website's file structure. In our example, that would be wherever the web server will look for items that would respond to requests from  https://www.yourwebsite.com/sugardev.

If your production instance is in /var/www/sugarcrm, then the new location would be /var/www/sugardev.

Restoring the Data to a New Database

You now need to create a new place for the data to reside. This process has two parts: creating a new database and running the backup SQL script to re-create the production database in the development database.

Earlier we used a command like this to create the SQL backup script:

  mysqldump -u myusername -pmypassword sugarcrm > sugarcrm-backup.sql

For our example, we will use the same database server to create a new database and hold the clone's data. The clone's database will be named "sugardev".

Use the following steps to create the new database:

1. From the server's command prompt, log into the database.
   mysql -u myusername -pmypqssword
2. At the MySQL prompt, create the new database. 
   create database sugardev;
3. Exit MySQL.
   exit;
4. Back at the command prompt, tell MySQL to run the backup script.
   mysql -u myusername -pmypqssword sugardev < sugarcrm-backup.sql

This tells MySQL to log in using the credentials provided, use the sugardev database, and run the backup script we made earlier. Once the script has run, MySQL will be exited. Your setup may be a little different from this. If so, ask your database administrator to guide you through the specifics of your environment.

Adjusting the Cloned Instance to Be Autonomous

Before attempting to run the newly cloned instance, you will need to make some small but very significant adjustments to it. At the moment, your clone still has absolute references to components of the production instance. These next few adjustments will redirect the cloned instance so it becomes its own autonomous instance. 

There are two files you need to adjust to give your new clone its autonomy: config.php and .htaccess. Both reside in the web root directory of your clone's code. Keep in mind that .htaccess is sometimes an invisible file. If you need help dealing with hidden files, contact your server administrator.

Updating the config.php File

There are six settings in the config.php which need to be adjusted:

• unique_key : This alphanumeric key must be different than the one being used for your production instance to make the clone uniquely identifiable. To adjust this, you can simply replace a couple of the number characters in the string with different number characters. 
• db_user_name : This is usually the user name used to create the database. If you are working in a higher security environment, ask your database administrator for guidelines concerning what database username to use.
  Note: If this is not set properly, you will experience a database error.
• db_password : This is the password for the db_user_name.
  Note: If this is not set properly, you will experience a database error.
• db_name : This is the name of the database into which you just imported the backup script. For our example, the value is db_user_name.
  Note: If this is not set properly, you will experience a database error.
• site_url : This must match the URL used to access the server from remote computers. For our example, the value is http://www.yourwebsite.com/sugardev.
  Note: If this is not set properly, some of the functionality of your site will fail to complete while some elements may appear on the screen.
• host_name : This the name part of the URL of the web server. For our example, the value is www.yourwebsite.com.
  Note: If this is not set properly, some of the functionality of your site will fail to complete while some elements may appear on the screen.

In most cases, all other values and variables should match those of the config.php file from the instance that is being cloned. For more information about MySQL, please refer to the MySQL Reference Manuals.

Note: If the instance you are cloning has Hint installed, you must make the clone uniquely identifiable by changing the unique_key and site_url settings as described above. See the Troubleshooting Inconsistent Behavior in Hint Insights article for more information.

Updating the .htaccess File

There is one line in the .htaccess file that must be altered for Sugar to function properly: the RewriteBase setting. This setting helps translate the URLs you pass to Sugar through the web browser into meaningful commands that the application can understand. In the .htaccess file, find the line that starts with RewriteBase. It will be followed by the directory within the root of the website (not the instance) where the instance root is. In our example, the original RewriteBase setting would be: RewriteBase /sugarcrm

For our example, we will change the value to: RewriteBase /sugardev

If this is not set properly, the instance becomes unresponsive and you will be presented with a white screen.

Conclusion

The entire cloning process can be summarized in these five steps. Once the clone is completed, it is available for your testing, and will have no impact on your production instance:

1. Copy the code (the files and directories in application root) and the data (the MySQL database exported into a MySQL backup script using mysqldump).
2. Paste the code into a new directory.
3. Use the database backup script to create a copy of the data in another database.
4. Adjust the unique_key, db_user_name, db_password, db_name, site_url, and host_name settings in the config.php file.
5. Adjust the RewriteBase setting in the .htaccess file.