SugarCRM Server Migrations Demystified

Perhaps one of the more interesting administrative tasks you might be required to undertake as a SugarCRM administrator is that of moving your installation from one server to another.  Your reason for needing to do this will likely relate to the retirement of the current server or perhaps simply moving from a hosted environment to an in house deployment.

Regardless, what makes the task interesting is the perceived complexity one might face in accomplishing the task. However, there is no reason to be nervous or worry.  Many of the potential challenges can be attributed to a handful of issues, mostly related to system configuration.


Let us begin with the most common issue: PHP configuration.


It is unlikely that the software configuration of the new server is an exact match of the system from which you are moving away.  This may seem like a minor issue, but in reality, this is the most common oversight in these type of operations.  To avoid the frustrations (and lost time) such an oversight might cause, you should first check the version of PHP and configuration (PHP.INI) on the new server and make sure that it is compatible with the version of SugarCRM you are currently using.  


A list of compatible versions of PHP, per SugarCRM version, is available on the SugarCRM web site.  Your findings might require you to either downgrade or upgrade the version of PHP on the new server prior to migrating the instance.


Often times administrators get themselves into trouble because in addition to migrating the instance to a new server, they also want to simultaneously upgrade SugarCRM to its most recent version.


Regardless of whether or not you have a need to upgrade SugarCRM as part of this process, the steps that should be followed to perform the migration from one server to another are:


1. Check new server configuration (and adjust if necessary) 
2. Copy SugarCRM program files from old server to new server 
3. Copy SugarCRM database from old server to new server
4. Modify SugarCRM's config.php file on the new server to update site_url and database settings


If you have a need to upgrade, it usually best to perform the upgrade after successfully migrating the instance to the new server.  Not doing so often leads to a number of problems and convoluted solutions that could have easily been avoided.


It is worth noting that some actions can also lead you into problems that might result in data loss, hence the importance of avoiding these traps. 


Here is a good example. 


Suppose your original server is running PHP version 4.4.x and SugarCRM version 5.0. You wish to move it to a new server that has PHP version 5.3 installed. At the same time, you would like to update SugarCRM to version 6.0.1. 


The problem with this scenario is that we can't simply copy it from the old server to the new and expect things to work. Version 5.0 of SugarCRM does not support PHP version 5.3, thus, would not function properly on the new server even if all files were copied correctly. Conversely, SugarCRM version 6.0.1 does not support version 4.4.x of PHP, so we also cannot simply upgrade SugarCRM on the old server as is without encountering other problems.


Many administrators opt for what seems like the simplest solution to the problem: install a fresh instance of SugarCRM 6.0.1 on the new server and then import the data from 5.0 or somehow try to connect the new instance of SugarCRM to the old database. I personally strongly advice against this technique.


For one, it requires intimate knowledge of SugarCRM in order to obtain a decent level of success.  In addition, it exposes you to potential loss of data, which is never a good thing. Equally important, if your system has a lot of customizations, there is a chance you might lose some or all of them, or they may not function as expected. In short, do not do this. 


The proper way of handling this is to find a common denominator between the two versions of SugarCRM, that is, find a version of PHP that is common to both.  In this case, reviewing the list of compatible versions tells us that PHP versions 5.2.1 - 5.2.5 are compatible with both.


Based on that information we can then downgrade the version of PHP on the new server to a version within that series and proceed to move our instance from the old server to the previously outlined steps. Once the move is complete, we can then upgrade SugarCRM to version 6.0.1 and if we like, we can also proceed to upgrade PHP to its original version of 5.3.


Of course, we could also do it the other way around and rather than downgrading PHP on the new server, we could upgrade PHP on the old server, perform the upgrade of SugarCRM and then move it to the new server. The potential problem here is that you might also need to upgrade other software, more specifically, MySQL, as SugarCRM 5.0 supports MySQL 4.1.x, but SugarCRM 6.x does not. 


The bottom line: always check the system configuration and SugarCRM software requirements before you begin!