Maintaining sites built with distributions

Last updated on
23 December 2016

Installing a Distribution

The installation process is similar to installing a standard Drupal site. The distribution is simply pre-packaged and configured with modules and themes. Some distributions also include sample content to demonstrate how it should be used.

Each distribution may contain additional installation steps and requirements. Make sure to review the distribution's installation steps.

Upgrading a Distribution

Note: Prior to any upgrade, please make sure to backup your site (database + files) and test the upgrade in a test environment prior to upgrading production.

Updating individual modules within a distribution is not recommended. Distributions may be a complex set of modules, themes, and libraries with specific versions and hand-picked patches applied. Manually upgrading individual modules, themes, and libraries may cause a patch to be lost or cause conflicts with other modules. Leave the headache of updating individual modules up to the distribution maintainers, and update your site to the latest versions of the distribution when they become available.

This is the recommended way of updating a standard distribution to ensure that Drupal core files are updated along with the distribution:

0. Backup and/or Test locally

Before starting the upgrade you should backup all your code and your database. This is essential, so you can roll-back if something goes wrong during the update!

Additionally, and highly recommended: Perform the update locally first.
You can do this by taking a snapshot of the code and database and running the site on a dev environment (Acquia/Pantheon/others) or a local web server. Go through all of the steps in this document locally, and if everything works, repeat the process on your live site. But don't forget, even with local testing, you should always backup the live site before upgrading.

1. Read the Release Notes

The Release Notes contain important information and extra precautions you may have to take, list which Features normally are overwritten etc. The Notes can be found as a link next to the download link on the Project Page.

Project Page Release Notes

2. Maintenance / Off-line Mode

Place your website in "Off-line" mode. This allows the upgrade process to update databases without interruption and to prevent site visitors from seeing error messages.

3. Copy Sites Folder

The /sites folder contains any content assets (files, images, etc.) along with environment specific configuration (e.g. settings.php). This folder (and sub-folders) are not provided by the distribution. Copy them to a temporary location so we can restore them later.
Note: Also evaluate the .htaccess and robots.txt file for local changes in the drupal root folder.

4. Delete Existing Files

Now that we've made a backup and a temporary copy of our /sites folder, we can proceed to deleting the whole docroot (and sub-folders). We do a complete replacement to ensure that updates include removing old code along with adding/updating new code.

Note for those using version control (git, svn, cvs, etc):
Your docroot/htdocs folder contains a folder containing version control information. If you are using a VCS, its recommended to remove all files within the folder, but not the containing docroot/htdocs folder or .git/svn/cvs folder within it.

5. Downloading Updated Distribution Code

If you have drush access, the simplest way to download the latest distribution code is:
$ drush dl <distribution_name>

If you do not have drush access then simply download the latest release from the distribution's project page and extract it to your docroot.

6. Restore Sites Folder

Copy the /sites folder we copied earlier back inside the docroot. Make sure to include .htaccess and robots.txt if necessary.

7. Run Updates

This will perform essential tasks to bring your database up-to-date with the latest version (if there are any). If you get any errors or warnings, run this command again until all of the updates are complete.

If you have drush access the simplest way to run updates is:
$ drush updb -y

Important: Drush needs ability to write to the files directory (run as sudo [not recommended], global write to files directory [also not recommended], or most likely, run as apache. To run as apache depends on your setup, but assuming apache runs as user "apache": sudo -u apache drush updb).

If you do not have drush access then visit [site.url]/update.php in your web browser.

8. Revert Features

Features (i.e. custom modules / exported configuration) have most likely been updated. Reverting features simply means we make the database match the code.

Warning: If you have made configuration changes that override a feature in the distribution then reverting those features will cause you to lose those changes. Ideally configuration changes will be made using Features Override (more info here).

If you have access to drush, you can revert features using:
$ drush fra -y

If you do not have drush access then you can access the Features Admin UI by going to /admin/structure/features. You will be provided a list of features that may be overridden. Clicking on a feature will let you choose which feature components to revert.

9. Clear Cache

Clear the Drupal cache at: /admin/config/development/performance

Or with drush: drush cc all

Note: If you get errors then you may need to rebuild your registry. This is sometimes necessary if modules have moved around during the update. You can rebuild your registry with or without drush by following the instructions on the project page: https://www.drupal.org/project/registry_rebuild

10. Disable Maintenance Mode / Go On-line

Take your website out of "Off-line" mode.