Upgrades and maintenance

As with any actively developed software project, you should anticipate the need to upgrade to the latest revisions and versions on a periodic basis, and perform regular maintenance on your system. Anticipating these needs and planning accordingly will greatly improve your long-term experience with CiviCRM.

Version and revision upgrades

The CiviCRM project follows conventional terminology for software releases:

• Versions: This terminology represents significant software releases with new functionality
• Revisions: This terminology represents minor releases and addresses bug, security, and functionality fixes

The core development team generally releases two major versions each year, and several minor revisions in between the major releases. The version number follows the conventional format as well: 4.6.4 = version 4.6, revision 4. You may track bugs and issues reported for a certain version through the CiviCRM issue tracker (https://issues.civicrm.org/).

In addition to this standard versioning model and release structure, CiviCRM has maintained an LTS release for the last several years, mostly maintained by the community. The idea behind an LTS release is to provide ongoing critical bug and security fixes for a selected version beyond the release of the subsequent version. As resources are limited, the CiviCRM core team typically only supports whatever is the current stable release. At the point Version 4.6 was released, the core team stopped actively supporting Version 4.5 releases (no new patches would be released for that version).

But many organizations are not willing or able to keep up with two releases a year, particularly if they have a large number of customizations that must be maintained. The goal of an LTS is to extend support for selected versions and reduce the upgrade pressure for organizations using it. In general, you will probably want to plan to upgrade with each major release. However, the presence of an LTS release gives you additional options should you choose to delay upgrading. With the forthcoming 4.7 release, Version 4.6 will become the new LTS release.

Since revisions typically correct bugs or address security issues, you should ideally implement them as soon as they are released. Revisions generally require minimal modifications to your database structure or data; so, the potential risk of running into any issues is less. CiviCRM will notify you in the footer, and optionally, through a popup of the administration interface, if a new release becomes available. If the release addresses security issues, this will be highlighted in the notification popup.

Before conducting any revision upgrade, back up your database and filesystem and test to ensure the integrity of the backup files. It is particularly important to have a reliable backup of your database, as you will need to restore the database to this version, should there be any problems during the database upgrade script process. It is also recommended that you perform upgrades on a development server before implementing on your live server. We consider it essential to use a development or staging server for sites that have custom templates and code.

Finally, if you made any modifications to CiviCRM files, including template (.tpl) and the CSS files, be sure to have a good record of your changes. You will need to review the changes against the new codebase and may need to adjust them. This is particularly true for major version upgrades, as the files are more likely to have significant changes.

CiviCRM provides some helpful tools for maintaining custom development work:

• Hooks: These tools are placeholders in the CiviCRM code where you can inject your own custom code. The benefit of hooks is that you are not actually modifying core files—your custom code is maintained separately and is injected into the code in the appropriate place. For more details on using hooks, visit http://wiki.civicrm.org/confluence/display/CRMDOC/Hook+Reference.
• Override directories: These tools are folders located outside of the core files where you can have modified versions of core files. CiviCRM first looks to see whether the file exists in the override directory, and if so, uses it. Override directories can be used for both PHP and .tpl (template) files. The override directories are configured in Administer | System Settings | Directories.
• Additional CSS: You can optionally configure an additional CSS file reference in Administer | System Settings | Resource URLS. The file will be loaded after the CiviCRM core CSS files, enabling you to override them with your own styles.

More details about the development of best practices are provided in Chapter 14, Customizing, Community, and Cooperation. As it pertains to upgrades, the essential takeaway is to understand that your customizations should be reviewed, updated, and tested thoroughly when you are implementing an upgrade. How you implement your customizations will also have a significant impact on the ease of upgrading.

Upgrade process

We will not walk through the upgrade process in detail for each CMS, as the bulk of the process is very similar, if not identical to the initial installation process. However, there are several general and CMS-specific recommendations and best practices we will review:

• Backup before you upgrade. Yes, we already said this a few paragraphs ago, but it's important enough to deserve repeating. In particular, be sure to backup and review your database before running the upgrade process.
• After you upgrade the files, you must run the database upgrade script. The path can be accessed at civicrm/upgrade&reset=1. You can also navigate to Administer | Administration Console to trigger CiviCRM's database check, which will notify you and provide a link if your database version is not aligned with the code base.
• In Joomla!, the installation of an upgrade can be done by installing the component over the existing installation (using the extension installer). This is generally adequate for minor revision upgrades. However, upgrading in this fashion leaves all existing files in place—even those that may no longer be needed and are not part of the upgrade. If you are upgrading to a major release, it is recommended that you uninstall, and then install the CiviCRM upgrade package to ensure the codebase is clean. Note that you may need to rebuild menu items after doing this.
• In WordPress, be sure to make a copy of your civicrm.settings.php file before you implement the upgrade. The file resides in the main civicrm package directory, which is replaced with the new package as part of the upgrade process. You will want to restore the settings file after implementing the upgrade.

Additional guidance and troubleshooting tips for installation and upgrades can be found at http://wiki.civicrm.org/confluence/display/CRMDOC/Installation+and+Upgrades.

After you finished your upgrade, you should consider whether you need to enable any new components or configure any new CiviCRM permissions. And in general, it's worth reviewing your configuration settings throughout the system after an upgrade—both as a way to periodically audit your configuration, and in order to review any new options available.

Moving an installation to a new server

If you are planning to move your website to a new hosting environment or from a development server to a live server, you will need to follow several steps in order to ensure that CiviCRM is configured properly in the new environment. The following content represents the key issues to consider and address when moving your site; a full discussion of steps to move a site can be found online at http://wiki.civicrm.org/confluence/display/CRMDOC/Moving+an+Existing+Installation+to+a+New+Server+or+Location.

After transferring your site's files and database to the new location, you must update several files to reflect the changes. CiviCRM references the root directory for your files and the full URL for the site in several locations. Follow these steps:

1. Modify civicrm.settings.php with the new directory and URL locations (and possibly database access details, depending on the details of your migration). In Drupal installations, this is most often found at /sites/default/civicrm.settings.php. Joomla! maintains two versions of this file, both of which must be updated (and which have slightly different references). You can find them at /administrator/components/com_civicrm/civicrm.settings.php and /components/com_civicrm/civicrm.settings.php. WordPress locates the file at wp-content/plugins/civicrm/civicrm.settings.php.
2. Delete the cached template files, which will be found at the following locations:
   • Drupal: <drupal-root>/sites/default/files/civicrm/templates_c/*
   • Joomla!:<joomla-root>/media/civicrm/templates_c/*
   • WordPress: <wp-root>/wp-content/plugins/files/civicrm/templates_c/*
3. Update the CiviCRM menus, which may use full URLs and must now reflect the new location:
   • Drupal: http://<drupal_site>/index.php?q=civicrm/menu/rebuild&reset=1
   • Joomla!: http://<joomla_site>/administrator/index2.php?option=com_civicrm&task=civicrm/menu/rebuild&reset=1
   • WordPress: http://<wp-site>/wp-admin/admin.php?page=CiviCRM&q=civicrm/menu/rebuild&reset=1
4. If any of the resources in your site reference the full URL or file location, you may need to update these (for example, if your navigation menu has links to profiles).
5. If you are using override directories (PHP or .tpl) or extensions, you may need to reset them to reflect the new file location. Go to Administer CiviCRM | System Settings | Directories. Also visit the Resource URLs configuration page to confirm that the values are set correctly.

After completing the move, be sure to test the site! Click on CiviCRM and confirm that the pages load as expected, and that the URL remains on your new site (if any outdated links exist, it may send you to your old domain or subdirectory).

System maintenance

As with any database system, there will be ongoing maintenance steps that should be performed on a periodic basis. Our focus in this section will be on basic maintenance steps specific to CiviCRM. It is outside the scope of this chapter to address the broader topic of server and MySQL database maintenance. Depending on the size of your database, and whether you are using a managed hosting service, you should be aware of basic maintenance steps with your database and hosting environment. Also, we will not address scalability-related issues and maintenance. However, as your system grows, you should be aware of the impact on your MySQL database performance and size.

The most important maintenance step with your system is to keep it updated to the latest revision, and not fall too far behind in major version upgrades. As the steps for doing that have been addressed earlier in this chapter, we won't go into detail here; but, we repeat it here because it is significant:

• Revision releases may contain security-related patches that are critical for maintaining a secure and safe database.
• Revision releases may contain bug-fix patches that are critical for maintaining a stable and fully operational system.
• Major version releases contain new features and functionality. If the new features are not something you will need or use, you may decide not to upgrade when it is first released. That's fine, and certainly not uncommon. But the core development team will only actively develop and patch the current stable version and current LTS release, which means there may be security or bug issues found in older versions, which are not addressed. As a general rule, you should avoid falling too far behind in the upgrade cycle for major revisions. Besides, there's lots of great functionality available in the new releases you'll want to benefit from!

Another important periodic maintenance step is dealing with duplicate contact records that have a sinister way of creeping into your system. This is particularly true if you have multiple forms collecting information from your public website, such as event registrations and contribution forms.

Duplicate records usually result from existing contacts completing online forms using an alternative e-mail address or nickname. As a result of the alternate data, the record does not match the existing record, thus causing a duplicate.

Fortunately, CiviCRM has some excellent tools for de-duping and merging your database, found under Contacts | Find and Merge Duplicate Contacts. The full range of these tools is detailed later in this book. For the purpose of maintenance considerations, you should schedule periodic deduplication of your entire database. Size and usage of your system will determine how frequently that maintenance should take place. After implementing your system, schedule an initial de-dupe/merge for 1 month from the go-live date. Depending on how many potential duplicates your de-dupe rules uncover, you can schedule the next maintenance review accordingly.

Tip

When covering the initial system configuration, we walked through the creation of the Cron jobs on your server to trigger automated events and actions. In most cases, these will continue to operate without the need for any intervention or maintenance. However, it is a good idea to periodically check in order to ensure that they are, in fact, running properly and the scheduled jobs are completing successfully. While creating the Cron job, you may choose to have a log sent to an e-mail address. The log does not contain much by way of detail, but will provide a verification that the script has completed successfully. You should make a habit of periodically checking the configured e-mail to confirm that your scripts are running properly.

Developing a backup policy and procedure

No chapter on maintenance would be complete without bringing up the topic of backup policies and procedures.

Regardless of where and how your contact database is being handled, it is pretty safe to say that the data stored in it is critical to the overall success of your organization and should be backed up regularly.

This consideration does not change just because your contact database now resides online. While you may have previously been content, relying on the standard backup policies of your hosting provider for your website, the inclusion of CiviCRM as a part of your website should now warrant a more robust plan and additional backup mechanisms to ensure your data is preserved and protected.

It is impossible to create a universal backup policy for all organizations. The traffic and usage of the system, nature of the organization, type of data you are maintaining, level of risk exposure, and other factors will all dictate what type of policy you should put in place. If you are uncertain what you should do, consider hiring an outside consultant to do a system and organization analysis for the purpose of developing a backup policy and procedure statement.

However, there are some universal rules and principles to consider:

• Don't rely on your hosting provider as your sole backup solution: Consider them a backup of the backup—should your own systems fail, they may be able to pull a recent backup and restore it. There are many reasons why you should not rely on them, but it all boils down to a lack of control. You don't have control over how they back up the database and files, when they do it, how frequently they do it, how long they keep the backup sets, how quickly they can provide you the files or restore it for you, or even if they decide to suddenly change their own policies without warning. The bottom line is: let the hosting providers perform their promised backups, but consider them your last line of defense.
• Create a formal policy and procedure statement: Yes, that's the main thrust of this section, and so it may sound repetitive. However, the point is to be intentional about creating a formal policy. This is important enough to go beyond a casual conversation with someone in the weekly staff meeting.
• Backups should be automated: Asking Jeff, the accidental in-house IT guy (who also wears six other hats) to run a backup every three days, is not a good policy. You need to know that the backup is happening without the need for human intervention.
• Periodically check your automated backups and verify their integrity: Nothing hurts worse than relying on, but never testing, your automated backup system. Suddenly, the server goes down and you discover that the .tar package is corrupt. Take the time to periodically unpack the backup, review the files, and actually import the database dump into an empty database to make sure it is complete and functional.
• In general, the database backup is far more important than the filesystem: Why? Most of your data, which is likely to be changing and worked on daily, is stored in the database. Your filesystem, that is, the application code, rarely changes. Understand that this is a general statement. If your website and CiviCRM makes a regular use of the file upload tools you will want to ensure those are backed up regularly as well. This statement is not to say that you shouldn't have a policy for backing up the filesystem; we are simply suggesting that you may not need the filesystem backed up as frequently as the database.
• Back up to multiple locations: Just as you don't want to rely on your hosting provider as the sole backup solution, you don't want to trust your office intranet or hosting server as the sole repository for backups. Wherever possible, create a system that will maintain regular backups in at least two locations.

Use these basic rules and invest your time and resources to ensure that your data is preserved in the case of accidental loss.

Tip

Joomla!, Drupal, and WordPress each have several extensions that will generate a periodic database dump, save it to the server, and provide options for transferring/storing it. We recommend considering the following tools:

• Drupal: Backup and migrate module is available at http://drupal.org/project/backup_migrate
• Joomla! and WordPress: Akeeba backup is available at https://www.akeebabackup.com/