This section outlines the requirements for doing a manual upgrade of Aegir to a new release. Before going ahead with this, you probably want to read the upgrade path and version-specific notes.

1. Conventions & Tips

All instructions and in general all commands must be run as aegir user, so all permissions are always set correctly.

To become aegir user you can issue this command:

su -s /bin/sh aegir

(Note you must run this as root or prefix with sudo).

Note that /bin/sh is an example. You may wish to instead use the shell of your choice, i.e /bin/bash

A standard umask of 022 is assumed. This is the default on most systems.

We assume that drush is in your path, if it is installed in /var/aegir/drush/drush.php, replace all occurences of drush by /var/aegir/drush/drush.php in the following steps, or add the following alias:

alias drush=/var/aegir/drush/drush.php

2. Upgrading drush and drush make

As part of your Aegir upgrade, you need to upgrade Drush to the latest stable version compatible with the target Aegir release.

If you are using the Drush Debian packages, the package should be upgraded through:

apt-get install drush

Otherwise, since drush 4.x is capable of upgrading itself, you can just run:

drush dl drush-7.x-4.5

If you are running a version before 4.x, use the following set of commands instead:

pear channel-discover pear.drush.org
pear install drush/drush-4.5.0

Note: you should use Drush version 4. Aegir 1.x does not support Drush 5, although 2.x does. Also note there is a bug in Drush 4.0 and 4.1 so you should use a version of Drush between 4.1 and 5.

Provision 0.4 has added a new dependency on drush_make, which will also need to be installed to upgrade the front end if you are upgrading from a pre-0.4 release.

If you are upgrading from an earlier 0.4 release, replace your copy of drush_make with the latest recommended release.

drush dl drush_make-6.x --destination="$HOME/.drush"

2.1. Upgrading to Drush 5

Note: those instructions are only relevant if you are ready to use the Alpha release of Aegir on the 2.x branch.

If you are upgrading to Aegir 2.x, you will need to install Drush 5 instead:

pear channel-discover pear.drush.org
pear install drush/drush

You should also remove your copy of drush_make from $HOME/.drush.

3. Upgrading the backend

After drush is updated, you must then proceed to upgrade the backend. The reason for upgrading the backend first before the frontend, is that the frontend upgrade process 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.

In general, we try to keep the backend and the frontend compatible with each other during release cycles. That is: provision 1.8 and hosting 1.9 will always be able to talk to each other, but hosting 2.0 will have trouble talking to the 1.9 backend, so you need to upgrade the backend first when you do a major upgrade (for example, 1.9 -> 2.0).

Bottomline: first you upgrade the backend, then the 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. Keep a copy of the old Provision and Drush in case something goes wrong in the frontend.

drush dl provision-6.x --destination=$HOME/.drush

To upgrade to 2.x, you will need a different commandline:

drush dl --destination=/var/aegir/.drush provision-6.x-2.0-alpha1

Note: the above will install the 2.0-alpha1 release of Aegir, which is the development release of Aegir, and is not considered production ready!

Note for 2.x users: Drush 5 has a commandfile cache which you need to clear before installing Aegir:

drush cache-clear drush

4. Upgrading the frontend

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.

Before upgrading, we set a few key variables to make the process easier. You must replace the arguments those variables to match your configuration. This means replacing $AEGIR_DOMAIN by the URL of your Aegir install, $AEGIR_VERSION with the version number of the Aegir you are trying to install, and also $OLD_AEGIR_DIR with the path to the previous directory where Aegir was installed.

OLD_AEGIR_DIR=/var/aegir/hostmaster-6.x-1.8
AEGIR_VERSION=6.x-1.9
AEGIR_DOMAIN=aegir.example.com

To upgrade your frontend, run the following commands, replacing the variables as described below:

cd $OLD_AEGIR_DIR
drush hostmaster-migrate $AEGIR_DOMAIN $HOME/hostmaster-$AEGIR_VERSION

4.1. Caveats

Since 0.4, the hostmaster platform is prepended with 'hostmaster' so as not to clash with any other Drupal platforms. If you are upgrading from Aegir version 0.3, your hostmaster platform may be called 'drupal-6.14'.

The directory passed to hostmaster-migrate must be an absolute path to where you want the new release to be stored.

Read the upgrade path notes again, you will have missed something.

4.2. What hostmaster-migrate does

The command will make sure the target directory is a valid Aegir install. If the directory does not exist, provision will use drush_make to fetch and assemble the correct version of the front end for the specific release of the backend you are running.

hostmaster-migrate will also completely replace the crontab entry for the aegir user.

The command above will fetch the latest stable Drupal release, so it can simply be run again when a new security release of Drupal is made available.

4.3. Special configurations and troubleshooting

If the upgrade fails, try running it again with the --debug flag:

cd $OLD_AEGIR_DIR
drush hostmaster-migrate aegir.example.com $HOME/hostmaster-$AEGIR_VERSION --debug

If you have customized your Aegir installation and are maintaining your own makefile, you can use the --makefile flag so the platform is created with another makefile than the default. Be warned that this may create problems if the makefile doesn't include the right Aegir modules.