.. -- mode: rst; fill-column: 78; -- .. This document is formatted using the ReST syntax.

==========================

Aegir Upgrade Instructions

This document describes briefly how to upgrade an existing Aegir installation

The document is laid out in the following sections:

• Conventions and tips
• Upgrade script
• Setting environment variables
• Generic upgrade instructions
  • Upgrading the backend
  • Upgrading the frontend
• Version-specific upgrade notes (read these before running anything else!)

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

Upgrade script

This document remains the canonical source of information regarding upgrading your Aegir installation.

However, an upgrade script exists in the Provision repository that tries to automate much of the process below.

It is imperative that you read the Version-specific upgrade notes located at the bottom of this document before attempting to run the upgrade.sh script, as the script will assume you have your system set up appropriately to handle the upgrade process.

You can download the upgrade.sh script with the following command.

Make sure you download it to somewhere that the aegir user can access in order to execute it.

Shell commands:: wget -O upgrade.sh.txt 'http://git.aegirproject.org/?p=provision.git;a=blob_plain;f=upgrade.sh.txt;hb=HEAD'

You may need to edit the script to set any variables that are different from the defaults. Pay particular attention to the OLD_DRUPAL_DIR variable, as you may be upgrading from a different release to the default here.

Shell commands:: su -s /bin/sh aegir -c "sh upgrade.sh.txt aegir.example.com"

Remember to replace aegir.example.com with the domain of your Aegir installation.

If you run this script (after satisfying the requirements of the Version-specific upgrade notes at the bottom of this document), you may skip the rest of this document.

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=HEAD export AEGIR_HOME="$HOME" export DRUPAL_DIR=$AEGIR_HOME/hostmaster-$AEGIR_VERSION export DRUSH_VERSION=6.x-3.3 export DRUSH_MAKE_VERSION=6.x-2.0-beta11 export AEGIR_DOMAIN=aegir.example.com export OLD_DRUPAL_DIR=$AEGIR_HOME/hostmaster-0.4-beta2

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"

Generic upgrade instructions

We aim to create a generic upgrade process that will be consistent across versions. This section describes this process. However, there are version-specific upgrade instructions that may be more relevant to your installation in the next section. You should check the version-specific instructions to ensure you have covered off the requirements necessary for successfully completing these version-generic steps.

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://files.aegirproject.org/provision-$AEGIR_VERSION.tgz gunzip -c provision-$AEGIR_VERSION.tgz | tar -xf - rm provision-$AEGIR_VERSION.tgz

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"

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.

Version-specific upgrade notes

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

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.

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

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

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

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;"

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.