Updating Open Atrium

Open Atrium Versioning and Releases

Open Atrium currently has a monthly bug and security update, and a quarterly Feature release. Security updates will be monthly unless it's a critical issue.

There is currently no automatic upgrade path from Open Atrium 1.x to 2.x, however there has been some work on creating a migration path.

These instructions are based on the 'Best practices for updating your Open Atrium site' webinar, created by the Open Atrium team.

Updating individual modules within the Open Atrium distribution is not recommended. Open Atrium is a complex distribution of over 200 modules, and updating a single module could cause issues in your site. Leave the headache of updating individual modules up to the Open Atrium maintainers, and update your site to the latest versions of Open Atrium when they become available.

This is the recommended way of updating a standard Open Atrium distribution to ensure that Drupal core files are updated along with the Open Atrium distribution. Read the instructions in full before following them.

0) Backup

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

0.1) Capture features customisations

Later on you will update all of Open Atrium's features to the latest version. It is therefore very important to capture any customization using Features Override before attempting to upgrade. See the 'Revert Features' step below for more information.

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 etc. The Notes can be found by clicking the version number of the download on the Project Page.

2) Disable your current site

Disable your memcache and/or varnish cache (or any other caching). If this is a public site, put it into Maintenance mode to prevent users from accessing it during the upgrade.

3) Save the /sites directory

The /sites directory normally contains all your site-specific customisation. So save this directory so that we can re-upload it in a later step. If you have modified the .htaccess or robots.txt files, save copies of those as well.

4) Download the new files

Download the latest version of Open Atrium from project page: https://www.drupal.org/project/openatrium

5) Delete existing files

Delete the entire contents of the web root directory: the directory Open Atrium is installed in. Do not simply copy the new files on top of the old ones. This will not delete old files that are no longer used and this could cause issues. You should have your old web root backed-up just in case!

6) Upload the new files

Upload the new version of Open Atrium into the web root directory.

7) Replace the /sites directory

Move or copy the /sites folder you saved in step 3 into the /sites folder of your new code.

8) Run updates

Run update.php on your site:
/update.php

Or with drush: drush updb

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).

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.

9) Clear caches

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) Revert features

Take extra caution here.

drush fra -y (Read notes first)

This command is required to update all of Open Atrium's features to the latest version. Running it will revert and overwrite any existing features, including any changes that you may have made to Open Atrium's configuration. It is therefore very important to capture any customization using Features Override before attempting to upgrade. This command can be run at any other time to restore Open Atrium's features to their default settings (Eg: if someone has inadvertently tampered with any Views or layouts within Open Atrium).

NOTE: You don't need to worry about anything *new* that you have added to your site, such as additional modules, custom content types, custom views, etc. You only need to worry about changes you have made to existing Open Atrium features, such as changes to Views or to existing Fields in existing content types.

If in doubt, assuming you made a backup in step (0), go ahead and revert all features and then check your site for any missing changes. Then you can restore your backup, save those changes using Features and try again.

11) Done! Re-activate site

Now that the site is upgraded, you can re-enable your Memcache, Varnish and other caches and take your site out of Maintenance mode. Your site is now up-to-date. Test it out!

---

Advanced notes

Updating the latest -dev version (for expert Drupal devs)

If you built your site using "git" and "drush" then you can use these same tools to update your site. First, save a copy of your Drupal sites/ directory as this will be overwritten by the update process. Next, go to the "openatrium" folder where you initially used "git" to fetch the Open Atrium repository. Use "git pull" to retrieve the latest version of the distribution. Then run the ./build.sh or ./build-dev.sh script exactly as before. Instead of pointing these scripts to your root web directory, you can point them to a temp directory in case the installation fails. The build.sh scripts delete everything in the target directory so building to a temp directory prevents your current web site from being lost if the build fails. Once the build is successful you can move the temporary directory in place of your web root, then restore the /sites directory that you previously saved.

If you just need to make a quick update of a specific open atrium module, you can also just go to that module directory and use "git pull origin" to pull in the latest changes without rebuilding the entire distribution.