Zurmo Configuration Primer Part 1

In previous posts, we learned how to quickly get a Zurmo CRM instance up and running on an Arvixe personal hosting account using Softaculous. In addition we discussed how to locate and access both the Apache and Zurmo logs. We also took a closer look at how easy it is to set debug level logging in order to troubleshoot your Zurmo instance. (and we strongly encouraged you to remember to reset Zurmo debug settings back to production values when you are done troubleshooting.right?)

In the next few posts we will be taking a deeper dive into Zurmo configuration. Along the way, I’ll show you some tricks that will enable you to reset your Zurmo instance without the need to re-launch the Softaculous installer. We will learn how to back up your configuration data in case of a disaster, and we will also learn a bit about how Zurmo works “under the covers”.

First some terminology. Zurmo developers use the term “instance” to refer to a single installation of the Zurmo CRM application.  Hence; the primary administrative configuration file is aptly named “perInstance.php”.

If you are using an Arvixe personal shared hosting account, this file is located in:


If you login to an Arvixe hosting account using ssh, as described in a previous post,

Use the following commands to list the contents of the config directory.

# change to zurmo configuration directory
cd www/zurmo/app/protected/config

# list the contents of the config directory
ls -al

drwxr-xr-x  2 user group 4096 Oct 17 19:36 ./
drwxr-xr-x 11 user group 4096 Oct 13 07:20 ../
-rw-r--r--  1 user group 22489 Oct  4 00:01 common.php
-rw-r--r--  1 user group 3597 Oct  4 00:01 console.php
-rw-r--r--  1 user group 7764 Oct  4 00:01 debugDIST.php
-rwxrwxrwx  1 user group 7765 Oct 17 19:36 debug.php*
-rw-r--r--  1 user group 4701 Oct  4 00:01 main.php
-rw-r--r--  1 user group 3798 Oct  4 00:01 perInstanceDIST.php
-rwxrwxrwx  1 user group 3866 Oct 17 19:36 perInstance.php*
-rw-r--r--  1 user group 5817 Oct  4 00:01 test.php

The very first thing you will notice is that there are two filenames that begin with

‘ perInstance’

As we will soon demonstrate, the perInstanceDIST.php file is a generic template that Zurmo uses to create perInstance.php. Thus, most of our critical configuration settings are going to be located in the latter file. Things like the database URI, administrative id and passwords, etc. will be stored here.

Let’s take a peek at perInstance.php that was generated for you by Softaculous (assuming you’re hosting at Arvixe, and used the autoinstaller from your control panel)

# open the perInstance.php file with the vi editor
vi perInstance.php

After scrolling past the Zurmo copyright stuff, you’ll see the production configuration. In our example we’ll be using the fictious Arvixe hosting account id:  YoUrLOGin_999, fake password: yOuRpasSWORD, and an example hosting domain named www.zurmozoo.com

    // Configure for production.
    $language         = 'en';
    $currencyBaseCode = 'USD';

    $theme            = 'default';

    $connectionString = 'mysql:host=localhost;

    $username         = 'YoUrLOGin_999';
    $password         = 'yOuRpasSWORD';

Nothing much earth-shattering about the first few lines of configuration, pretty much what you might expect.

The next few lines deal with memcache.  If available, Memcache is used by Zurmo as a way to achieve faster runtime performance.  If you are going to be doing any serious development work in Zurmo, you’ll want to gain a firm understanding of how memcache works and its configuration, but that is outside the scope of our discussion at the moment. In fact, at the current time, Arvixe personal hosting accounts seem to have memcache disabled for policy reasons, so you might want to give serious consideration to upgrading to a VPS or dedicated hosting account once you begin attracting larger more demanding clients. I’m referring to projects where Zurmo excels as a development platform, not just for CRM.  But I digress.  Point being, Zurmo will run just fine with or without memcache. You’ll notice it is not enabled in the following section of our configuration.

$memcacheServers = array( 
        'host' => '',
        'port' => 0, 
        'weight' => 100,

Next up, is the admin email. Easy peasy. This is the email where you want any admin email from Zurmo to be sent.  In the past, you may have been advised to use some generic email like info@yourdomain.com or admin@yourdomain,com.  However; as we live in the age of spam, so shall we modify our public email addresses in ways arcane and confounding. I won’t pretend to give you any further advice on this subject, except to say that if you read about some email cloaking technique on the internet, chances are it’s already obsolete. So you might find it more productive to focus some energy on your spam filter.


Now the next two items are particularly interesting. The first, $installed, is a flag that Zurmo checks before processing any request.  If this flag is set to ‘false’, Zurmo execution will pass to the Zurmo installer module.  Yep, Zurmo comes complete, out-of-the box, with a very slick installer, and we are going to demonstrate it in the next article. For now, it’s enough to be aware of the purpose of the $installed variable.

The second item is a flag for maintenance mode. It will redirect any new requests to a splash screen, so you can block user activity while performing maintenance on the site.

$installed = true; 
$maintenanceMode = false;

Another really cool feature of Zurmo, is its ability to integrate custom code in a modular, mostly upgrade-safe way. I say mostly, because there is still a tiny bit of wiring you need to do in the Zurmo source if you really want to take advantage of Zurmo as a base for further customizations.   The next three lines which sets the value of the $instanceConfig variable is used to assign an array of custom configuration variables.  We’ll definitely be reviewing this feature in a lot more depth in a future article. At this time it’s enough to note that ‘hostinfo’ is the root location of your website domain, and the ‘scriptUrl’ element defines the path to the application index file.

$instanceConfig   = array(); 

       = 'http://zurmozoo.com';
= '/zurmo/app/index.php';

Likewise, if  you need to extend or override the default (Yii framework) url manager, for example if you were writing say, a custom API – Zurmo once again comes to the rescue with the ability to configure url routes via simple array assignment.

$urlManager = array ();

Finally, the remaining lines in the default perInstance.php (as installed in Arvixe by Softaculous) attempt to include another perInstance file, perInstanceConfig.php in the runtime path, and also set some global constants, which as the comments warn, should not be messed with.  (Naturally, I’ve substituted fake values for the constants in the code below).

“Now wait a minute!,” you exclaim.  “Why just a minute ago, you said there were TWO perInstance files, and now there are THREE!”

Whoa! Chill out. Take a deep breath. This alleged third ‘perInstance’ file, does not even exist at this time. It’s used as part of the customization hooks we talked about earlier. Please don’t jump to conclusions – really, you worry me sometimes. The code below says ‘IF’ perInstanceConfig.php exists – not that it does exist. Of course we’ll be including this one in our upcoming tutorial on Zurmo upgrade-safe customization.

if (is_file(INSTANCE_ROOT . '/protected/config/perInstanceConfig.php'))
        require_once INSTANCE_ROOT . '/protected/config/perInstanceConfig.php';
    define('ZURMO_TOKEN', '12d34r56ki9843r');

    // Never modify this value below manually or system will not be able to decrypt encrypted passwords.
    define('ZURMO_PASSWORD_SALT', 'zbjojdk989384ef');

At this point you should have a sense of some of the configuration variables that control a typical Zurmo CRM installation instance. Don’t worry if it still seems a bit confusing.  You now have the theoretical foundation for the next lesson, where we will roll up our sleeves and completely trash our newly installed Zurmo instance, then magically reconstitute it using saved values from our perInstance.php file.  Don’t panic, you heard right, we’ll be doing a controlled demolition. After it’s over, your confidence is guaranteed to increase – it’s kind of like doing the fire-walk at a Tony Robbins seminar.  Now might be a good time to back up your perInstance.php to a safe secure place, preferably on your desktop!

(c) 2013 Windsor Wallaby. All rights reserved.

Tags: , , , , , , , , , | Posted under Zurmo | RSS 2.0

Author Spotlight

Windsor Wallaby

Windsor Wallaby

Windsor Wallaby is an independent and enthusiastic Zurmo CRM supporter and Open Source contributor. Active on the Zurmo user forums and a regular personality on the weekly Zurmo developer's conference call, Windsor is committed to building helping relationships by Listening, Learning, Doing, and Sharing. Windsor works with Zurmo CRM daily to track business opportunities and contacts. Windsor also integrates Zurmo as a core platform component for in-house and bespoke IT development projects.

Leave a Reply

Your email address will not be published. Required fields are marked *

9 + 8 =

You may use these HTML tags and attributes: <a href="" title="" rel=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>