Table of Contents

Upgrading CiviCRM

Upgrading Core

Upgrading CiviCRM in a multisite is not too different from a regular upgrade. The major differences are that you have to put many rather than one CMS-site in maintenance mode and that there are more caches to clear.

Once you have reviewed the client manifest and verified that no customizations will break from a standard upgrade, follow these steps to upgrade CiviCRM:

  1. Login with an admin account to the site that is to be upgraded
  2. Put all the sites in maintenance mode, then clear all their caches: $ drush -y @sites vset --exact maintenance_mode 1 $ drush -y @sites cc all
  3. Backup the files and databases for the instance that is to be upgraded.
  4. Download the new tarball.
  5. Delete CiviCRM.
  6. Unzip the tarball.
  7. Verify the filesystem permissions for the unzipped CiviCRM files. Access for the devs group and the www-data user are ensured by filesystem ACLs (getfacl/setfacl), but traditional file permissions act as a mask, so you must ensure that group has read/write (so developers can read and edit files, should the need arise) and that user has read (so that Apache can read them). See Filesystem Permission Scheme for more information.
  8. Delete all CiviCRM caches: $ rm -rf /path/to/webroot/sites//files/civicrm/templates_c/
  9. Visit /civicrm/upgrade?reset=1 in your browser to run the database upgrades.
  10. Take the sites out of maintenance mode: $ drush -y @sites vset --exact maintenance_mode 0 $ drush -y @sites cc all
  11. For good measure, visit /civicrm/clearcache in your browser. Sometimes Angular pages don’t work following an upgrade or a restaging without this step.

Upgrading Extensions

Extensions which use schema versioning present a problem for a multisite. This is documented in CRM-19252.

Extensions may choose to define upgrade steps in their upgrader classes which make changes to the database. The steps are represented as upgrade_N steps, where N is an incrementing integer.

When these steps are run, CiviCRM stores the N value to be sure that the upgrade step isn't run twice, as this may cause database errors or other abnormalities. The N value is stored in the civicrm_settings table under the name org.example.myextension:version.

The problem occurs when running a CiviCRM multisite. CiviCRM stores the setting as domain-specific, so it is possible to have org.example.myextension at version 1101 in Site A and 1103 in Site B. When this is the case, users on Site A will be advised to run the extension upgrades though they have already been run by Site B.

Short-Term Solution

I’ve created a script which keeps everything in sync. It upgrades/installs the extension into domain 1, then updates the org.example.myextension:version setting for each domain based on domain 1’s setting.

For more info:

/var/www/ -h

Long-Term Solution

I've made a pull request to civix which moves the extension version into a domain-neutral space. This has been merged, but developers will need to update civix and update the civix templates in each extension before it has any impact.