community.aegirproject.org

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.

This guide is not the official upgrade instructions for your system. It merely explains the purpose of UPGRADE.txt and what it actually does. You must follow the UPGRADE.txt precisely in order to upgrade your system.

UPGRADE.txt

In a similar fashion to the Install instructions, the upgrade process for Aegir resides in an UPGRADE.txt that ships with each release inside the 'Provision' component.

It is kept in each release so that it may be versioned, as some upgrade steps may and often do differ between releases.

The UPGRADE.txt is stored in the 'docs' directory of the Provision component, which gets installed in /var/aegir/.drush/ on standard systems. However, the announcement for each release (published here and on the mailing lists) always contains a link to the UPGRADE.txt, so you'll probably find it's easier to fetch it from there.

Each time a new release of Aegir is made, there may be some 'version-specific' notes contained towards the bottom of the file. The reason for this is that sometimes a change in Aegir requires a new change or modification of some other component of your server. This might include adding, removing or changing a line in MySQL's /etc/mysql/my.cnf, or changing the location of an 'Include' path in Apache to read configurations from a new location.

Because these modifications typically require administrative privileges to perform, they can't be automated or run by the system 'aegir' user on your server. This is the reason these notes are included in the UPGRADE.txt.

** It is extremely important that you read the version-specific notes before following any other instructions in the UPGRADE.txt.**

If you fail to apply any of the version-specific steps and proceed with the generic upgrade process, that process is likely to fail.

Upgrade process

The typical upgrade process outlined at the start of the UPGRADE.txt is as follows:

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

upgrade.sh.txt

An upgrade.sh.txt is mentioned in the UPGRADE.txt. 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.