How to install Aegir 1.x on Ubuntu 11.10

Aegir is a hosting system for deployment and management of large network of Drupal sites. It allows developers and site administrators to automate many of the common tasks associated with deploying and managing large websites. Aegir makes it easy to install, upgrade, deploy, and backup an entire network sites.

Here I document how I installed and configured Aegir 1.5 on a headless Ubuntu 11.10 server. The server has 1024MB RAM, and it's a bare Ubuntu server, with OpenSSH server and fixed IP address, on a local network.

Pre install configurations

Aegir requires that the hostname is a fully qualified domain name (FQDN). It means that the hostname as returned by hostname and uname -n resolves to the IP address for the server. So we are going to change few config files, in order to get Aegir working in a local network.

Static IP: set static IP address at /etc/network/interfaces like this, but change the particular parameters as your local network requires:

auto eth0  
iface eth0 inet static  

Hostname: change the default hostname at /etc/hostname. I use here myhost.local as the hostname. You are free to change, as long as it remains FQDN.

echo 'myhost.local' | sudo tee /etc/hostname  

DNS resolution: for the sake of simplicity, I just update /etc/hosts, in order to get the DNS resolution for the hostname set above.

echo ' myhost.local' | sudo tee -a /etc/hosts  

Software requirements

This section describes what is expected to servers Aegir is running on. It needs a webserver, so we are going to install Apache, but Aegir runs smoothly on Nginx stack, as well. We need PHP (Aegir documentation suggest 5.2, but since Drupal 7 is compatible with PHP 5.3, and PHP 5.3 is the default for Ubuntu 10.4, we are using 5.3). The database server will be MySQL, a mail transfer agent (Postfix), and few other utilities: git, unzip and rsync.

sudo apt-get update  
sudo apt-get upgrade  
sudo apt-get install apache2 php5 php5-cli php5-gd php5-mysql mysql-server  
sudo apt-get install postfix git-core unzip  

During the install process you have to answer few questions.

  1. set and write down (!) the MySQL root password
  2. configure Postfix as Internet site, and set system mail name to your hostname (this is myhost.local in this howto)

LAMP configurations

PHP Configuration: Some complex installation profiles or distributions require a PHP memory limit that is higher than the default. The PHP command line tool should be configured to use 192Mb of RAM. The default PHP configuration is OK with its default of 128Mb:

sudo sed -i 's/memory_limit = -1/memory_limit = 192M/' /etc/php5/cli/php.ini  

Apache configuration: Aegir assumes a few Apache modules are available on the server, and generates its own configuration files. The way we enable this is by symlinking a single file which contains all the configuration necessary. The installer script creates the configuration file referenced by the newly created symlink. The aegir user needs to have sudo access. Add the relevant line to your sudoers file.

sudo a2enmod rewrite  
sudo ln -s /var/aegir/config/apache.conf /etc/apache2/conf.d/aegir.conf  

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, so we are commenting out one line in MySQL config. And you need to restart mysql, to clear any caches.

sudo sed -i 's/bind-address/#bind-address/' /etc/mysql/my.cnf  
sudo service mysql restart  

Aegir install

Aegir user: Aegir requires that the scripts run as a non-root system account, and the configured system account needs to be a member of the web server group. Aegir assumes its user called aegir, its home directory is /var/aegir and the webserver group is www-data. In addition we will create a directory layout for Aegir configuration and backups, set a password and the default shell.

sudo adduser --system --group --home /var/aegir aegir  
sudo adduser aegir www-data  

Add sudo rights for Aegir user: the aegir user will have to reload the Apache configurations, when a new domain is added. Therefore it needs sudo rights for that. This step is a bit tricky, due to security setting in Ubuntu server.

echo 'aegir ALL=NOPASSWD: /usr/sbin/apache2ctl' | sudo tee /tmp/aegir  
sudo chmod 440 /tmp/aegir  
sudo cp /tmp/aegir /etc/sudoers.d/aegir  

Drush install: Aegir is heavily relying on Drush, which should be installed by the aegir user. So switch user to aegir, download and untar Drush. You can play with Drush different versions as well.

sudo su -s /bin/sh - aegir  
gunzip -c drush-$DRUSH_VERSION.tar.gz | tar -xf -  
rm drush-$DRUSH_VERSION.tar.gz  

It worth to set a symlink, to get a short path to drush:

sudo ln -s /var/aegir/drush/drush /usr/local/bin/drush  

Install Aegir components: we are using then drush to install the Aegir components. First switch to the aegir user:

sudo su -s /bin/sh - aegir  

Then set the required Aegir version, and install the provisioning backend:

drush dl --destination=/var/aegir/.drush provision-$AEGIR_VERSION  

Now install the hostmaster frontend, which is Drupal 6 with the hostmaster profile, including drush_make:

drush hostmaster-install  

During this step you will be prompted for the information necessary to complete the installation, like Aegir frontend URL (the myhost.local), or the MySQL root password and the admin user e-mail. Most of them can be left on default.

Start to use

At this point, you have checked out all the code and setup your basic Drupal system (Drupal core, hosting, hostmaster and eldir) that will be the Aegir frontend and the backend system. Your filesystem layout is at /var/aegir/. The installation will provide you with a one-time login URL to stdout or via an e-mail. Use this link to login to your new Aegir site for the first time.

Do not forget to add myhost.local to the hosts files of all the other servers on your local network!

Optional patches

For advenced users is worth to consider some patches to drush_make, depending on versions. Aegir uses drush_make 2.2 from Aegir 1.0 to Aegir 1.2. From Aegir 1.3 to Aegir 1.5 drush_make 2.3 is used.

Recommended patches to drush_make 2.2

Recommended patches to drush_make 2.3

  • Nested makefiles: Allows to use different versions of the same project in nested make files


Kudos to the Aegir-team for that great toolset!

You can find a condensed script of all the commands above, at my Github repo.