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 Overview

2.1. Upgrading drush

As part of your Aegir upgrade, you need to upgrade Drush to the latest stable version compatible with the target Aegir release. AEgir 1.x only works with version 4.5. Versions 5 - 7 have been known to work with AEgir 2.x, however the Drush developers recommend version 6 as the most stable.

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

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

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

3. Upgrading to AEgir 1.x

3.1. 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. Aegir 1.x does not support Drush 5, although 2.x does.

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

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.2. Upgrading the 1.x backend

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

3.3. Upgrading the 1.x frontend

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.

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

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

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

4. Upgrading to AEgir 2.x

4.1. Upgrading drush

Install Drush 6.x per the directions given at the Drush repository. The maintainers have deprecated the PEAR installation procedure and are encouraging everyone to install Drush via the Composer dependency management tool.

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

4.2. Upgrading the 2.x backend

Upgrading the backend is as simple as replacing your copy of Drush & Provision 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 --destination=/var/aegir/.drush provision-6.x-2.0

Drush 5+ has a commandfile cache which you need to clear before installing Aegir:

drush cache-clear drush

4.3. Upgrading the 2.x frontend

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.

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

OLD_AEGIR_DIR=/var/aegir/hostmaster-6.x-1.11
AEGIR_VERSION=6.x-2.0
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.4. Special configurations and troubleshooting

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

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.

If the update fails due to a bug in module Hosting, it will ask you to run "drush hostmaster-resume help". That command does not exist. Try this one instead.

drush --debug @hostmaster hostmaster-resume /var/aegir/hostmaster-6.x-1.11 /var/aegir/hostmaster-6.x-2.0