Aegir Drupal


Install the Cloudflare Drupal plugin to restore visitor IP information. Since Cloudflare acts as a proxy. Aegir is a powerful hosting system that sits alongside a LAMP or LEMP server to create, deploy and manage Drupal sites. Latest release notes: 3.18 With Aegir, you can setup a Drupal site in just a few clicks. Aegir Hosting System. Aegir is a powerful hosting system that sits alongside a LAMP or LEMP server to create, deploy and manage Drupal sites. Latest release notes: 3.18 With Aegir, you can setup a Drupal site in just a few clicks. Aegir is a hosting system for Drupal powered sites based on many Drupal itself (for Aegir core), Drupal deployment tools, and the Drush. Aegir makes it simple This tutorial covers how to install Aegir and use it to deploy Drupal sites on a Debian VPS. Platforms - the actual Drupal installation, such as Pressflow or Drupal 7 Sites - anything that lives in sites/ directory After the initial installation, Aegir will have one (sometimes two) server with local web server and database (Apache2 and MySQL in this example), one platform called hostmaster with one site (called localhost in.

  1. Aegir Drupal 8
  2. Aegir Drupal
  3. Aegir Drupal
  4. Aegir Drupal 9
  5. Aegir Drupal 8

I had started this series with a post about what features will be evaluated when selecting DIY Drupal hosting solutions. We shall start with the most simplest and earliest solution of them all, Aegir. First, the nomenclature. Aegir is the God of seas and oceans in Norse folklore, much like Varuna in the Hindu pantheon. If Drupal is associated with water drops, it only makes sense to associate a lot of Drupal sites with something relating to the sea or ocean after all! And Aegir stands true to this metaphor.

Aegir architecture

Aegir has an opinionated view of a Drupal site. Instead of having core and a set of modules and themes checked in, Aegir recommends a Makefile based approach. The former model works equally well on Aegir, as we will see. A drush makefile is more like a snapshot of your Drupal site's code. It contains the version of every module used, all the patches applied to them, and specific installation instructions. All the configuration is stored in features and Aegir heavily relies on a features-based workflow. This set of makefiles, modules and instructions are tagged as a single drupal profile, and this constitutes a 'platform', in Aegir lingo.Each platform can have multiple instances(or sites) running on Aegir.

For example, this site will be modelled as 'lakshminp blog' platform in Aegir. This will comprise of a set of contrib and custom modules, themes and features tagged as a single Drupal profile. This could be a custom profile, or some contrib profile, like Panopoly. There will be multiple sites running the 'lakshminp blog' platform, like the live site, a staging version, a dev version where I'm adding a new feature or fixing a bug. Each of these multisites will be using the same code base and will be modelled as Drupal multisites.

If each of your websites is as unique as a snowflake, then you will have to create an Aegir platform for every site and run an instance of the site on that platform. As a corollary, Aegir suits you best if you have sites with similar functionality/features, as there is lesser administrative overhead involved. Here's where Aegir shines. If you are having a critical security update in core or a contrib module, you have to create a new platform by patching the respective module and simply migrate all the site instances from the old platform to the new one.

Aegir rests on 3 pillars, Hostmaster, provision and drush. Hostmaster is a Drupal 7 install profile which runs the Aegir frontend. Provision is essentially the backend of Hostmaster and contains a set of drush commands like verifying new platforms, creating new instances, adding servers etc. There are other terms which you will hear often when discussing about Aegir, like Eldir, the default theme of Hostmaster(cleverly named, as Eldir is the servant of Aegir), and Hosting, the set of modules which power the Hostmaster installation profile. This is where you need to lay your hands on if you want to extend Aegir's functionality.

Aegir architecture

Aegir Drupal

Installing Aegir

The best pick to install Aegir is to use an open source elaborate shell script provided by the nice folks at Omega8. You can try installing an Aegir setup while reading this post. I've tested it on a DigitalOcean(that's an affiliate link BTW) box and the accompanying screenshots are from there. It shouldn't be too different on other VPS providers. Omega8 recommends using a Debian 8 system to install it, which you can do so in the DigitalOcean interface,

DigitalOcean DNS setup for Aegir

I'd suggest that you use a $10 box to try out the setup. You can always scale it up later(very convenient, that). Make sure you are able to ssh as root into the system. After this, you have to download and run a pre-install script,

This will install another script called boa. BOA is an acronym for Barracuda Octopus and Aegir. Barracuda is the base system which will install the main instance of Aegir, OS related dependencies and the Hostmaster platform. Octopus is the name given to one or more 'satellite' instances where you can install the platforms. Aegir, because, well, the system is powered by it. In essence, a bare minimum BOA setup will consist of one machine, with Barracuda and Octopus running alongside Aegir.

The Aegir model of a drupal site

We've seen how Aegir views your site, i.e. as an instance of an Aegir platform. The first step in creating a new site or importing an existing site into Aegir is creating a platform out of it. A platform can be as sophisticated as a drush makefile, or just the codebase of your existing site. Aegir can take in both, but recommends the former approach, for 2 reasons:

  • Our codebase is lean as it contains only the metadata, not the code itself, i.e. the module names, locations(where to download them or git clone them etc.), the versions, the exact patches to be applied. I've seen Drupal codebases grow monstrous and taking a lot of time to clone and setup. A drush makefile based build, especially when applied along with caching strategies works like a charm. Besides, there is also no duplication of code.
  • There is no way a hack or a quickfix can seep into your code, as every tiny patch is thoroughly documented in the makefile.

So, makefile or otherwise, your first step is to extract your codebase in a path recommended by Aegir and let Aegir verify this. Once this platform is successfully verified, you can start adding sites to that platform.

Running updates

Client Acme's ecommerce site could be a platform, and their live site, an instance of this platform. Let's assume that you have 4 other clients with the same set of features, you could add an instance for each of them on the same platform. Now, if there is a security update for one of the modules in this platform, you create a new platform with the fix for that module, and migrate all the instances from the older platform to the newer one.

Aegir can run Drupal 8

Aegir can comfortably run a Drupal 8 site and most of the popular Drupal 8 distributions. The idea being the same, i.e. platform-ize a site, and create new instances out of that platform. There are some limitations though, at the time of writing this, Aegir does not support a composer based Drupal 8 workflow, which IMO is not a mainstream practice in D8 yet. This shouldn't stop you from using Aegir to launch and manage Drupal 8 sites. There have also been attempts to run other PHP frameworks in Aegir with various degrees of success. This could be a killer feature if implemented.

Final tally

Being one of the first and earliest implementations of DIY Drupal hosting, Aegir is a tried and tested stack. Omega8 has excellent support and provide hosted Aegir instances. Big shoutout to them for open sourcing huge parts of their business back to the community.

Aegir's strengths are its simplicity and its close alignment with Drupal's nuances, like multisite, drush, installation profiles etc. It works best for running bulk updates across sites. This kind of workflow is Suitable for large number of websites with similar profiles. Ex: Universities, brochureware style sites.

Aegir Drupal 8

Though it serves well for one segment, platform and feature based model is not a good fit for all sites. This point led to creating another awesome tool in the DIY ecosystem, which we will look at next.

DIY Drupal hosting series

DIY Drupal hosting using Aegir - you're here

View the discussion thread.

  • Upgrade Guide
    • Manual Upgrade
      • Upgrading Overview
    • Upgrades with Debian packages
      • Custom distributions
      • Rolling back the upgrade

Upgrading Aegir is designed to be as easy as it possibly can be, and regularly improves over time as the developers attempt to streamline the process for users.

Nonetheless, the upgrade process can seem a little daunting to users. This is mainly because some expectation arises that because Aegir is built on Drupal, and is made for managing Drupal sites, it seems reasonable to expect the upgrade process to be as straightforward as, say, upgrading a regular Drupal site.

Aegir is a powerful system that goes beyond a normal Drupal application by being split into two parts: a frontend (the browser-based control panel) and the backend (bits on the system in /var/aegir, such as Drush and Drush extensions), along with a system user on your server that runs command-line scripts and restarts services, and cronjobs.

Typically what this means is that when it comes time to upgrade Aegir, you not only have to upgrade the frontend site, but also update the components that reside in the 'backend'.

But don't panic! We have instructions and even a script to run, to take care of almost all of it for you, eliminating as much as possible the chance for human error.

Upgrade options

There are three options you can choose to upgrade your Aegir install when a new release comes up:

  • Upgrades using Debian packages
  • Upgrades using the script
  • Manual upgrades

New release of Drupal core

Just as you would use the Migrate task in Aegir to upgrade one of your sites to a new copy of Drupal core, you can follow the UPGRADE.txt to upgrade your actual Aegir frontend system to a new copy of Drupal core too. The upgrade process (including the script) will always fetch the latest available copy of Drupal core to place the frontend on.

Currently you cannot upgrade the Aegir site itself from the frontend with a Migrate task as you do for your managed sites. This may change in the future as we have an open issue over at Allow upgrade of hostmaster sites from the frontend.

Major upgrade from Aegir 6.x-2.x

Most of the instructions on this page are targetted to minor updates, e.g. Aegir 3.1 to 3.2.When upgrading from Aegir 2.x there are a few extra precautions to take. But apart from that the normal upgrade options apply.

To avoid the upgrade breaking run these drush commands:

The upgrade will complain about missing modules like modalframe and jquery_update. This is to be expected, and can be ignored.

This upgrade path is tested by Jenkins.

Manual Upgrade

This section outlines the requirements for doing a manual upgrade of Aegir to a new release. Before going ahead with this, you probably want to read the upgrade path and version-specific notes.

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

Upgrading Overview

Upgrading drush

As part of your Aegir upgrade, you may need to upgrade Drush to the latest stable version compatible with the target Aegir release. Aegir 3.x works with Drush 6, 7 and 8. Note that to install and manage Drupal 8 sites, Drush 8+ is required.

Upgrading the backend

After drush is updated, you must then proceed to upgrade the backend. The reason for upgrading the backend first before the frontend, is that the frontend upgrade process is instigated by the backend using Drush Make. Thus you need to be running the new backend first in order to successfully produce a new frontend.

In general, we try to keep the backend and the frontend compatible with each other during release cycles. That is: provision 3.2 and hosting 3.3 will always be able to talk to each other, but hosting 3.x may have trouble talking to the 2.x backend, so you need to upgrade the backend first when you do a major upgrade (for example, 2.4 -> 3.0).

Bottomline: first you upgrade the backend, then the frontend.

Upgrading the frontend

Once your backend is upgraded, you can upgrade your frontend. Think of this as the backend fetching a new copy of Drupal core and the Hostmaster frontend application onto your server, and then moving the Aegir site's settings.php and other bits and pieces over to the new codebase.

The hostmaster-migrate command

The command will make sure the target directory is a valid Aegir install. 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.

drush hostmaster-migrate will also update the crontab entry for the aegir user.


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.

If there is a newer release of Aegir than what you have installed, the hostmaster command will fetch the latest stable Drupal release. If you have the latest stable version of Aegir already installed, this won't happen because Drupal core changes could affect the stability of the distribution. So it cannot simply be run whenever a new security release of core Drupal is made available (unless your instance was installed via the unstable channel, which is not recommended).

To upgrade Drupal core (say for a new security release) while running Aegir stable, this method should work, but make sure to test on a development instance before running on your production environment:

Aegir Drupal

  1. Become the Aegir user.
    • sudo -Hsu aegir
  2. Upgrade Drupal core.
    • drush @hostmaster pm-updatecode drupal
  3. Verify the upgraded platform.
    • drush @platform_hostmaster provision-verify
  4. Verify the Hostmaster site.
    • drush @hostmaster provision-verify
  5. Run database updates
    • drush @hostmaster updatedb

Upgrades with Debian packages

Regular update process

Make sure you have the Aegir repository in your sources.list, as per the installation docs.

If you want to upgrade all packages in one shot, use:

Note that you can upgrade Aegir in steps. Upgrading your backend to the Debian package should be as simple as running:

Upgrading the frontend to the Debian package works identically:

As during install, you can use the DEBUG variable to run Drush in debugging mode:

Note on contrib modules: some Aegir-specific contrib modules may have been installed on your Aegir deployment. This may fail if you are doing a major upgrade. In this case, you will probably want to disable those contrib modules. Look for directories in ~/.drush or /usr/share/drush/commands or other components of the Drush commandfiles search path, and move them out of the way. After the upgrade, download the new versions of the modules that are compatible with the new Aegir release.

Aegir Drupal

Temporarily upgrading to the unstable Debian package

Occasionally, you might be facing a bug that has been fixed in Aegir's git repos, but hasn't made it into a new release yet. The Aegir Project's CI system automatically builds and uploads new Debian packages for each commit to one of the core repos. As such, you could download and install the .deb directly. Note that this is not recommended.

  1. Ensure that the latest build is passing the test suite.
  2. Visit
  3. Find the latest unstable release packages for aegir3-provision and aegir3-hostmaster (they'll be the ones with a long suffix).
  4. Download the Provision package to your Aegir server (e.g., wget aegir3-provision_3.7+438.10e2f5b_all.deb)
  5. Download the Hostmaster package to your Aegir server (e.g., wget aegir3-hostmaster_3.7+438.10e2f5b_all.deb)
  6. Install the Provision package to your Aegir server (e.g., sudo dpkg -i aegir3-provision_3.7+438.10e2f5b_all.deb)
  7. Install the Hostmaster package to your Aegir server (e.g., sudo dpkg -i aegir3-hostmaster_3.7+438.10e2f5b_all.deb)

The idea here is that you're only running the unstable version of Aegir until the next full release, at which point the normal update procedure (e.g., apt-get install aegir3) will install the next stable release.

Upgrading from non-Debian installs

The Debian package supports migrating from existing installs. You will need to move /var/aegir/.drush/provision out of the way before going ahead:

You'll also need to go through steps 1 through 3 of automatic install on Debian.

Then just install the package as if you were installing from scratch.

Custom distributions

Aegir Drupal 9

If you have your own makefile, you can go ahead with the above process, but change the makefile to the one you want:

Usually no questions are asked when upgrading - this allows you to specify the makefile path for your custom distribution of Aegir, even if you're upgrading. It's also how you can switch distributions.

An example aegir-koumbit.make file could look like:

Keeping custom distributions up to date

Aegir drupal

This section describes how to upgrade the code for custom distributions in between debian package upgrades. Here, we assume that Aegir is already installed through the debian package.

Create a new Aegir makefile, or update the custom Aegir makefile. (You can use the makefile in as a starting point.) Add modules/features/themes/libraries/whatever to the makefile. Ex:

Follow the manual upgrade path:

Hope it's all green (no errors). If there are errors, fix the makefile.

A new platform should exist, the new site should be in there, verifying. If the task is not running, check that hosting-queued is running. If it's not, restart it using /etc/init.d/hosting-queued force-reload. (Since hostmaster changed location, hosting-queued may have crashed at this point.)

When the debian package is upgraded, it should create a new hostmaster platform automatically. (You can test this with dpkg --configure.)

Rolling back the upgrade

If something went wrong with the upgrade, you can rollback by deleting the hostmaster site and redeploying on the older platform:

Then edit the alias to make the following changes:

  1. change the platform to point to the older platform alias
  2. change the platform root path
  3. change the site path

During the upgrade, a backup was done end you need to find which backup file it was in the backups directory. Use this backup to redeploy the older platform:

Recovering a Failed Upgrade

When using the regular update process and you encounter an error it leaves the debian package in a broken state.

First you need to figure out why it failed. For example is there a permission problem? Once you determined the issue correct it and clean up the environment. It may be necessary to remove the new hostmaster platform. It is up to you to determine what state Aegir is in.

Next you need to fix the broken package by running the fix-broken parameter:

Aegir Drupal 8

This tells the debian package system to start through the process again.

Upgrades with script

This page describes the upgrade script in the Provision repository that tries to automate much of the upgrade process.

It is imperative that you read the version-specific upgrade notes before attempting to run the script, as the script will assume you have your system set up appropriately to handle the upgrade process.

Aegir Drupal

You can download the script for Aegir 3.x with the following command:

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

You may need to edit the script to set any variables that are different from the defaults, for example to upgrade to a different Aegir version.

To do the upgrade, just run the script: