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.

2. Setting Environment Variables

To make following instructions generic and not dependant on a concrete Drupal or Aegir version, we will use shell environment variables. 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'.

You should replace the following variables for current versions at the time you are reading this document.

Shell commands::

export AEGIR_VERSION="6.x-1.0-rc3"
export AEGIR_HOME="$HOME"
export DRUPAL_DIR=$AEGIR_HOME/hostmaster-$AEGIR_VERSION
export DRUSH_VERSION=7.x-4.4
export DRUSH_MAKE_VERSION=6.x-2.2
export AEGIR_DOMAIN=aegir.example.com
export OLD_DRUPAL_DIR=$AEGIR_HOME/hostmaster-6.x-1.0-rc2

This document also assumes drush is installed properly and we use an environment variable to simplify the documentation again.

Shell commands::

export DRUSH="php $AEGIR_HOME/drush/drush.php"

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.

Shell commands::

cd $AEGIR_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
cd $HOME/.drush
mv provision ../provision.bak
wget http://ftp.drupal.org/files/projects/provision-6.x-$AEGIR_VERSION.tar.gz
gunzip -c provision-6.x-$AEGIR_VERSION.tar.gz | tar -xf -
rm provision-6.x-$AEGIR_VERSION.tar.gz

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.

Shell commands::

$DRUSH dl drush_make-$DRUSH_MAKE_VERSION --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.

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

Shell commands::

cd $OLD_DRUPAL_DIR
$DRUSH hostmaster-migrate $AEGIR_DOMAIN $DRUPAL_DIR

The directory specified must be an absolute path to where you want the new release to be stored. 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.

This command will completely replace the crontab entry for the aegir user, and asks for confirmation before it does so. If you do not confirm, the process will be halted as it is necessary for the task queue to be processed.

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.

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.