SugarCRM deployment efforts

Since we started working on SugarCRM in the office, one of the hardest tasks that we had was solving the deployment issue.  On one hand, SugarCRM comes with some really nice GUI tools, such Studio and Module Builder.  On the other hand, the system is large and complex and should be developed and tested in a separate, non-production environment.

We’ve spent a lot of effort over the last couple of month trying to solve the puzzle.  The problem is that there is a tricky combination of files updates and database changes, some of which can be just copied over while others have to be executed from the destination machine’s administration.

So, what we did first was complete separation of environments.  Each developer had his own machine on which he could install and configure as many instances of SugarCRM as he saw fit.  Also, each developer had a separate branch in the Subversion, so that he could work on his own stuff without being afraid to run into conflict with anyone.

After that, we created a development server with a checkout of common trunk.  For extra insurance, we did a checkout from a system user, who does not have any write permissions in the repository.  In this case, even if someone will accidentally try to commit from the development server, we would be sure that it fails.

Now, each developer had to merge his changes into trunk, and then test them on the development server.  This procedure is very similar to the production deployment and consisted of two parts.  Firts part was updating all the relevant files (a bit more on this in a moment) with svn update.  Second part was logging into SugarCRM and doing Admin -> Repair -> Quick Repair and Rebuild.

The graphical tools that come with SugarCRM are powerful, but a bit confusing.  The biggest confusion for me was (and maybe still is) between Module Builder and Studio.  Studio can be used to customize core modules that are shipped with SugarCRM.  The results of these customizations are stored in custom/modules directory, and when loaded into the database, can be observed in _cstm tables (for example, accounts_cstm).  This is where new custom fields and things like that are going.  Module Builder is a tool which can help you customize existing modules or build the new ones. The confusion here is because both of these tools can be used to do the same things.  But with Module Builder you’d be working closer to the core system and modifying “original” functionality.  You can build your own modules too, by the way.  The results of the Module Builder work with go into modules/ directory, and changes in the database will take place in the original tables.  One thing to remember though, is that you’ll need to push Save & Deploy button every time you are finished with changes in Module Builder.  This is like compiling and building a module.  If you forget this step, then your module will hang in its source somewhere around custom/modulebuilder directory.

Another thing to keep in mind is the sillyness of the machine trying to figure out another machine.  Meaning that Subversion will often have issues trying to figure out the changes from the last commit, and these issues would be often caused by a lot of automatically generated code by SugarCRM.  In most of these problematic cases, Subversion will just merge the changes, and this would often result in a broken system.  I’ve found at least two reasons behind these: small context size that Subversion uses (3 lines or so) confuses it sometimes, bringing it to a wrong place in the file to do the merging; and rather messy automatically generated stuff by SugarCRM – unnecessary reordering and mixed (DOS and UNIX) ends of lines in a single file.  These problems are mostly related to vardef files (vardef.php and anything *def.php) and language dictionaries (anything with *en_us*php, or whatever your locale is).  The solution we are using at the moment is simple, although a bit heavy on the manual work – instead of merging the changes and checking them every time we simply remove old versions of files and add the new ones in two separate commits.  These way Subversion treats the files as completely different ones and real removes and re-creates them instead of trying to merge.

We follow exactly the same procedure now to deploy to the production server.  We just merge code from trunk/ to branches/stable , commit, then update the files on the production server, and then do the Quick Repair and Rebuild.

The thing about Quick Repair and Rebuild is that it takes the update definitions of your forms and layouts and rebuilds compiled templates.  It also compares the structure of the database with the update definitions in the files and, if needed, updates the database scheme too.  Sometimes you’d get an error of missing table (usually custom tables with _cstm suffix) – just create an empty table manually.  Put a couple of standard fields like id_c, date_modified, and date_entered.  After that, field modifications should be OK.  In case you run into a problem with updates to several fields at once, make sure that SugarCRM put a semicolon (;) at the end of each SQL statement that it shows you in a popup window.  For some weird reason, sometimes it just works, and sometimes it tries to execute several queries without separating them one from another.

So far the setup seems to be working for us just fine, but I’m sure that we’ll have a few changes here and there.  I’ll let you know once we find any better way of doing things.  In the meantime, here are some links that might help your development efforts:

Read 8 comments


  1. Thanks for the overview.

    One question: How do you handle fields created by Studio? That seems to be the only way to add new fields to Sugar’s standard modules. I’ve found that Sugar stores the definition of new Studio fields not in a vardefs file, but inside the database in the fields_meta_data table. The only code customisations that Studio makes are updating the forms through detailviewdef, editfiewdefs and the like (using 5.1RC, but 5.0 does the same).

    So, if you add a field with Studio and commit your change, the only thing you’re committing is the new forms, not the new field because that is kept in the database.

    Do you export/import these custom fields from database to database? Or do all your development copies use the same database?


  2. Sander,

    for the time being, adding new fields through Studio requires a bit of a manual work. Here is the process that we follow:

    1. Add field in Studio
    2. Find the changes that SugarCRM did in custom/modules/MODULE/MODULE_vardefs.php . Cut them out.
    3. Append changes from the previous step to modules/MODULE/vardefs.php
    4. Remove lines that mention custom_field or custom_module
    5. If needed, add var definition to the list in modules/MODULE/MODULE_sugar.php
    6. Do “svn commit”
    7. Do “svn update” on the development or production system
    8. Do Quick Repair and Rebuild on the same system, so that SugarCRM updates database scheme


  3. I forgot to mention that you need to change MODULE above to the specific module that you are working with. And, also, that you don’t have to use Studio to add fields -- you can do them manually, once you get used to it a bit. Check the link to Vardefs wiki page at the end of the post -- it covers this.


  4. Leonid,

    What version of Sugar are you using? I’ve tested 5.0.0g and with that, Studio does not create/update the fields in custom/modules/MODULE/MODULE_vardefs.php. It only updates the layouts (detailviewdefs, editviewdefs). The field itself isn’t stored in a vardef file but in the database in the fields_meta_data table.

    If that has changed with 5.1 I’d be very happy. It’s much better to have such field definitions in the code than in the database :-)


  5. Sander,

    we are using a patched version of 5.0.0a. We merged some of the updates up to 5.0.0g, but not all of them yet. It’s strange that you have such a difference in behaviour on the same base version.

    The thing about files and the database is that you can control the database structure from the files. When you do Quick Rebuild and Repair, SugarCRM checks for the differences, and applies them to the database scheme if needed. This is the way to move database changes around, from development machine to production.

  6. Pingback: Keeping SugarCRM under Subversion control - Lone Wolves - Web, game, and open source development


  7. More in depth details of the way to maintain deployment to production machine would have been more in place. you just talk much about svn & versioning and the details of the module creation process but nothing really useful just a nice starter lead.


  8. Studio is little bit tricky part for me but for you, it seems to be a nice try. Capability and flexibility of SugarCRM ensures that you won’t go out of Sugar deployment. One can meet their business requirements well by changing the deployment methods as the business increases or expands.

Leave a Reply