This section outlines the requirements for doing a manual upgrade of Aegir to a new release.

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

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 installing a new version of Drush and Provision over the old ones.

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

These are generic instructions to upgrade your hosting, hostmaster, eldir or Drupal core installation to new versions. As of 0.4 this process has largely been automated, and will be able to upgrade 0.3 and any of the 0.4 development releases to the latest applicable versions.

Once you have upgraded the backend, and you have installed drush_make you will need to run the hostmaster migrate command.

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.

5. Version-specific upgrade notes

5.1. Bleeding-edge HEAD dependency

If you intend on upgrading your system to the bleeding edge version of the code from our git repositories, you will need the git program installed. On Debian, this means:

Shell commands:

apt-get install git-core

5.2. 0.4 - DNS Configuration

Aegir requires that the hostname returned by the hostname and uname -n shell commands, resolves to the IP address for this server.

Shell commands as root:

AEGIR_HOST=`uname -n`
resolveip $AEGIR_HOST

If the command returns your IP address, you are all set. If it returns an error you will need to edit your /etc/hosts file.

(Mac OSX notes: if you are running on OS X you will not likely have a resolveip binary. Just substitute ping $AEGIR_HOST ).

First line of this file looks like:

127.0.0.1 localhost

Simply add all domains you want to this line. e.g:

127.0.0.1 localhost $AEGIR_HOST $AEGIR_DOMAIN other1 other2

To be clear you cannot put $AEGIR_HOST $AEGIR_DOMAIN in your hosts file. Put in whatever uname -n returns for $AEGIR_HOST and what ever domain you want to use f or $AEGIR_DOMAIN (real domaion or faked in hosts file). In OS X uname -n will return whatever you put in System Preferences -> Shareing -> Computer Name. I added that value (iMac 27 for me) to /etc/hosts and my faked aegir domain as follows:

127.0.0.1  localhost  iMac27  aegir.local

If you only intend to use Aegir on a single server, it is acceptable for the resolved IP address to be the '127.0.0.1' loopback address.

If you intend to manage multiple servers using Aegir, you will need to make sure that the IP address is the public IP of this server.

Finally, set an $AEGIR_IP environment variable for use in the Database configuration step below.

Shell commands as root:: AEGIR_IP=resolveip $AEGIR_HOST | awk {'print $6'}

(If running OS X or are otherwise missing resolveip and you just want to use Aegir on your computer use you can do this: AEGIR_IP=127.0.0.1

5.3. 0.4 - unzip dependency

As of the 0.4-alpha3 release, 'unzip' is a required dependency on your server in order to successfully extract the jquery.ui library that is part of some UI improvements. On Debian, this means:

Shell commands::

apt-get install unzip

5.4. 0.4 - Database configuration

To make sure that the Aegir backend, and all the possible web servers can reach your database server, you need to configure mysql to listen on all the public IP addresses available to it.

/etc/mysql/my.cnf configuration line to comment out:: bind-address = 127.0.0.1

Now you need to restart mysql, to clear any caches.

Shell command as root:: /etc/init.d/mysql restart

Because you have already installed Aegir when it was using the generic grants, you will need to create new grants using the public IP address and hostname of this server.

Shell command :: mysql -uroot -p mysql

You need to generate the following grants using the hostname returned by the uname -n command, and the IP address that the resolveip command returns for that hostname.

You need to re-use the pasword you had for the account before.

Shell commands::

mysql -u root -p -e "GRANT ALL ON *.* to 'aegir_root'@'$AEGIR_HOST' IDENTIFIED BY 'xxxx' WITH GRANT OPTION;"
mysql -u root -p -e "GRANT ALL ON *.* to 'aegir_root'@'$AEGIR_IP' IDENTIFIED BY 'xxxx' WITH GRANT OPTION;"

5.5. 0.4 - Apache configuration

This release introduces multi-server support and required reorganizing the Apache configuration files in ~aegir/config. Instead of having all files in config/vhost.d, they are now split between vhost.d, platform.d and a single apache.conf. The vhost.d directory is for virtual hosts, platform.d is for platform-specific configuration and apache.conf is the server-wide configuration file.

You will need to change the line you added to either the httpd.conf file or /etc/apache2/conf.d/aegir file during installation.

Open your httpd.conf file and modify::

Include /var/aegir/config/vhost.d

To read ::

Include /var/aegir/config/apache.conf

If you are upgrading from 0.4 releases between alpha8 and (including) alpha14, you will need to rename your conf.d directory to post.d in Apache and pre.d in Nginx. Example, in Apache::

mv /var/aegir/config/server_master/apache/{conf.d,post.d}

Now log into Aegir, and verify the hostmaster platform. This will generate the correct apache.conf file and restart Apache.