community.aegirproject.org

Warning: this documentation is being re-written to bring all the documentation from the source code (UPGRADE.txt and so on) directly into this manual, so those documents may change and fluctuate over time. See this post for progress reports.

Upgrading Aegir is designed to be as easy as it possibly can be, and regularly improves over time as the developers attempt to streamline the process for users.

Nonetheless, the upgrade process can seem a little daunting to users. This is mainly because some expectation arises that because Aegir is built on Drupal, and is made for managing Drupal sites, it seems reasonable to expect the upgrade process to be as straightforward as, say, upgrading a regular Drupal site.

Aegir is a powerful system that goes beyond a normal Drupal application by being split into two parts: a frontend (the browser-based control panel) and the backend (bits on the system in /var/aegir, such as Drush and Drush extensions), along with a system user on your server that runs command-line scripts and restarts services, and cronjobs.

Typically what this means is that when it comes time to upgrade Aegir, you not only have to upgrade the frontend site, but also update the components that reside in the 'backend'.

But don't panic! We have instructions and even a script to run, to take care of almost all of it for you, eliminating as much as possible the chance for human error.

Warning: this documentation is being re-written to bring all the documentation from the source code (UPGRADE.txt and so on) directly into this manual, so those documents may change and fluctuate over time. See this post for progress reports.

Upgrade process

The typical upgrade process outlined in the sub-sections of this document are as follows:

• Read and apply the version-specific notes
• Read the conventions and tips
• Run the upgrade.sh.txt script, or the next three manual steps:
• Set the environment variables
• Upgrade the backend
• Upgrade the frontend

upgrade.sh.txt

An upgrade.sh.txt exists per the Automatic upgrade steps. This automates the last three steps listed above, including backing up old components first. The upgrade.sh.txt has to assume that you have read and completed the version-specific steps first before attempting to run it.

Manually upgrading

Alternatively if you don't wish to run the script, you may proceed to export the environment variables. These are just abstractions to avoid having to re-type the same URLs or version numbers of Aegir and other components, which would otherwise introduce extra potential for human error.

After your environment variables are exported, you must then proceed to upgrade the backend. The reason for upgrading the backend first before the frontend, is that the frontend upgrade process (explained further below) is instigated by the backend using Drush Make. Thus you need to be running the new backend first in order to successfully produce a new frontend.

Upgrading the backend is as simple as replacing your copy of Drush, Provision, and if necessary, Drush Make, with the new versions if available. These manual steps are provided to you in the UPGRADE.txt; you can literally copy and paste the steps into your terminal and expect good results.

Once your backend is upgraded, you can upgrade your frontend. Think of this as the backend fetching a new copy of Drupal core and the Hostmaster frontend application onto your server, and then moving the Aegir site's settings.php and other bits and pieces over to the new codebase.

The procedure for upgrading the frontend is entering your old hostmaster directory, (say, /var/aegir/hostmaster-$old-version) and running 'drush hostmaster-migrate $youraegirdomain.com'.

The precise steps for performing this, just like the earlier parts, are all provided by the UPGRADE.txt. You can copy and paste the commands provided and you should get good results if you followed all the earlier steps.

Did we remind you to read the version-specific notes first? This is the most common pitfall for users trying to upgrade their system.

New release of Drupal core?

Just as you would use the Migrate task in Aegir to upgrade one of your sites to a new copy of Drupal core, you can follow the UPGRADE.txt to upgrade your actual Aegir frontend system to a new copy of Drupal core too. The upgrade process (including the script) will always fetch the latest available copy of Drupal core to place the frontend on.

Currently you cannot upgrade the Aegir site itself from the frontend with a Migrate task as you do for your managed sites. This may change in the future, but has not been developed yet.