Introduction

While respecting the change policies, this document describes how to add, update and remove modules installed in any given platform.

Handy tips

This document assumes you have a drush command in your path, and that it is ran as the aegir user. This is now working out of the box on this server, with the new Drush Debian package.

You may still want to setup an alias for drush since you will very likely use sudo to run drush. Your alias will probably look something like this:

alias drush="sudo -u aegir drush"


You can put that command at the end of your ~/.profile to make sure it is ran every time you connect to the server.

This document also assumes you work from the aegir home directory (~aegir or /var/aegir) unless otherwise noted.

cd /var/aegir


Those commands need to be ran through the shell, and you need appropriate permissions from the sysadmin committee (which is given upon request and with a proper reason to CT members). Eventually, this will be controlled by the Hosting frontend so this manual fiddling will not be necessary.

Creating a platform

To create a new platform, you need to use Drush. It's as simple as:

drush dl drupal


This will download the latest stable Drupal release (6.12 at the time of writing) into the current directory (which, as mentionned above, should be /var/aegir).

Do not forget to add the usual locales to the platform (Drupal >=6.x). Supported languages are listed in /var/aegir/translations/README.txt with the command to download and install them using drush.

Once the code is downloaded, you need to add a "platform node" so that the frontend knows about the new platform.

Platform are named after the CMS (ie. only "Drupal" right now, excepted when we import existing sites, see below), its version (e.g. 5.14) and its status (e.g. "dev" or "prod"). If the platform is the default platform, it should have "(default)" in its title. An optional extra version can be added to follow module updates.

The platform name is used as the platform node title and the directory name. So for example, the default platform right now is named ''Drupal 6.11-prod (default)'' and the directory should be (but isn't, for historical reasons) drupal-6.11-prod (note that we omit the default).

Updating modules in a platform

You need to create a new platform every time you do an update on a prod platform module, as specified in the change policies. The new platform is basically a copy of the old platform, with one or a few modules updated.

Since you do not upgrade core, you will have conflicts in platform names, so this is where the optional extra version (mentionned above) comes in handy: you can use it to avoid conflicts with the previous versions. So say you are upgrading views on the 6.12 platform, but not the core (which is wise). You will create a new 6.12 platform named: "Drupal 6.12-1.0-prod". The next iteration, if necessary, will be 6.12-1.1.

When the new platform is created, you can start migrating sites to it. That will take care of running the update.php and changing all the required configuration in the backend.

So the general steps are as follows:

1. create a new platform
2. copy the modules from the old platform
3. update the modules code

Broken down into commands, that is:

1. creating a new platform:
   mkdir tmp ; cd tmp
   drush dl drupal
   mv drupal-6.12 ../drupal-6.12-1.0
2. copy the new modules:
   cp -r drupal-6.12/sites/all/* drupal-6.12-1.0/sites/all/
3. update the modules
   cd drupal-6.12-1.0/sites/all
   rm -r views
   drush dl views

Migrating sites between platforms

When a new platform is ready, it needs to be tested. Clone a few critical sites (allmodules.site.koumbit.net, koumbit.org sites, etc) to the new platform to test the (and fix) migration path. Then all sites in the platform can be migrated en masse.

Adding modules to a platform

Adding modules is simpler: just download the module in the sites/all/modules directory of the relevant platform.

cd sites/all/modules
drush dl views


Removing modules from a platform

This is more tricky: removing modules can have serious impact on existing sites and should not be taken lightly. Basically, don't do this.