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 usually also upgrade Drush to the latest stable version. 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:

export DRUSH_VERSION=7.x-4.4
cd $HOME
mv drush drush.bak
wget http://ftp.drupal.org/files/projects/drush-$DRUSH_VERSION.tar.gz 
gunzip -c drush-$DRUSH_VERSION.tar.gz | tar -xf -
rm drush-$DRUSH_VERSION.tar.gz

If you are using Debian packages, the package should be upgraded through apt-get.

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"

3. Upgrading the backend

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 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 0.3 and hosting 0.3 will always be able to talk to each other. hosting 0.2 was able to talk to provision 0.3 too, but the API is not well enough defined so that can be counted upon.

Therefore, you want to keep the frontend and the backend in sync. When you do a major upgrade (e.g. 0.3 -> 0.4) of the backend, you must upgrade the frontend soon after.

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

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.

export OLD_AEGIR_DIR=/var/aegir/hostmaster-6.x-1.7
export AEGIR_VERSION=6.x-1.8
export 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.

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.