Newer
Older
.. -*- 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=provision-0.4-beta2'
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::
mig5
committed
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=0.4-beta2
export AEGIR_DIR=/var/aegir
export DRUPAL_DIR=$AEGIR_DIR/hostmaster-$AEGIR_VERSION
export OLD_DRUPAL_DIR=$AEGIR_DIR/hostmaster-0.4-beta1
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_DIR/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_DIR
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
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.
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
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;"
--------------------------
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::
Adrian Rossouw
committed
Adrian Rossouw
committed
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.