Creating A Platform in Aegir

A platform is a codebase on which Aegir can deploy your websites - it could be Drupal 6.15, Drupal 5.21, Pressflow, Prosepoint, Acquia Drupal, or Open Atrium. At the least, think of a platform as a copy of Drupal core, against which your sites are provisioned upon. Typically what distinguishes a Platform is its custom install profile (such as the case of OpenAtrium, ManagingNews and so on) and custom extra modules, libraries or themes.

When Aegir has these codebases, or platforms, it allows you to easily setup new sites and upgrade existing sites by 'migrating' them to a new platform.

For example, let's say you have a Drupal 5.21 site that you want to upgrade. You visit that site's node in Aegir (each site has its own 'node' in Aegir containing metadata about the site), select the Migrate tab and it shows you the compatible platforms to migrate to. Depending on what platforms you have set up, this might include Acquia Drupal and Drupal 6.15. You then select the platform you wish to migrate the site to, click 'Migrate' and Aegir does the rest - effectively copying the sites/example.com directory from one platform to another, then running the update.php. If there are no errors it then removes the sites/example.com directory from the old platform and changes the Apache vhost files - and your site is upgraded!
See the separate page Migrating / Upgrade Sites for more information on this.

That is the power of Platforms. We'll now step through setting up new codebases as platforms in Aegir...

1. Setting Up The Codebase On Your Server

A platform is nothing more than the Drupal codebase or similar, with any install profiles, modules and themes included. So all you need to do to setup a basic codebase is untar a fresh Drupal codebase into a folder on your server. A good place is to create a 'platforms' directory under the /var/aegir path, and then create the new platforms in subdirectories of that.

So you might have /var/aegir/platforms/drupal-5.21 and /var/aegir/platforms/drupal-6.15 for example.

You can see a selection of available Drupal installation profiles to use as platform under Aegir further down this page.

For a standard Drupal platform, the easiest is to simply use drush:

php /var/aegir/drush/drush.php dl drupal-6.15

For other packages you can use wget, subversion, CVS, Git, FTP or any other way you'd normally get code to your server!

You can simply use the 'wget' command, for example:

You could use CVS, eg:

Or you could use subversion:
svn co https://svn.acquia.com/drupal/branches/1.x-6.x .
(Note the dot at the end, that's important)

Make sure all files are owned by aegir user this way a platform can be deleted through the website too.

chown -R aegir:aegir .

2. Creating The Platform in Aegir

It is necessary to inform Aegir of the new platform that has been placed on the server. A Platform is defined as another content type in the main Aegir system, within which you can create nodes storing metadata on the platform for Aegir's knowledge. We'll do that now.

In the Aegir web interface, select 'Create Content' and then 'Platform'. Simply enter the name you want to give the platform (such as 'Drupal 6.15'), and the path to the codebase (such as '/var/aegir/platforms/drupal-6.15').

Now, click 'Save' and Aegir will add a task to its queue to verify the Platform. If there are any site folders in the /sites/ directory, it will also attempt to import those existing sites (note that Aegir ignores sites/default though. If you have a site in sites/default/, it must be renamed to /sites/$yoursite.com/ in order to be recognised).

When the task has been processed successfully, you'll have a new platform ready to use to create sites with.

3. Potential Problems and Their Solutions

If the initial verification of the platform doesn't seem to start at all, you may have a problem with the cron job that runs the tasks. There's a section in the FAQ to help with this.

If the task is processed but turns red with an error symbol, then click on the task to see a log of what happened. Look for any red lines. It's most likely to be a file ownership or permissions problem. Check that the codebase is owned by the aegir user and either the aegir or www-data group. Check the permissions on the files in the codebase. The most common cause is that you have not configured a MySQL superuser capable of creating more databases, and the database connection test has failed.

If this doesn't solve the problem, browse through the documentation in this group, or visit the issue queue.

4. A Selection of Available Codebases for Platforms

Drupal 6

Drupal 5

Acquia Drupal

ProsePoint

Open Atrium

Managing News

Pressflow

Tattler App

Here are the installation profiles available on drupal.org.

There is nothing stopping you from writing your own custom install profile with relevant contrib or custom modules, themes and libraries tailored to your needs, in order to rapidly provision and deploy sites specific to your customer or use case. This is indeed the way that Aegir is intended to be used.

How to write an installation profile