Manual Upgrade

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 is capable of upgrading itself, you can just run:

drush dl drush

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.

Shell commands::

drush dl drush_make-6.x-2.2 --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.

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

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_AEGIR_DIR
drush hostmaster-migrate aegir.example.com $HOME/hostmaster-$AEGIR_VERSION

In the above you must replace the arguments to "cd" and "drush" to match your configuration. This means replacing aegir.example.com by the URL of your Aegir install, $AEGIR_VERSION with the version number of the Aegir you are trying to install (e.g. 6.x-1.0-rc6), and also $OLD_AEGIR_DIR with the path to the previous directory where Aegir was installed (e.g. hostmaster-6.x-1.0-rc5).

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