Introduction

Aegir installation seems difficult at first, but once you get around it, it's fairly simple. It's 3 basic steps::

1. Install system requirements
2. Configure system requirements, which include:
   • configure the webserver, database, DNS, PHP, etc
3. Create the Aegir user,
4. Install the backend (Drush & Provision) and the frontend (with hostmaster-install) with install.sh.

Note that these instructions setup a complete Aegir system. If you want to only setup a new remote web/db server, it should be sufficient to install the system requirements (step 1), configure them (step 2) and follow the Remote server how-to.

These instructions provide example commands for a Debian-like distribution, but should be fairly easy to adapt to other environments. In fact, this document is meant as a canonical reference that should work on every platform and that can be used for people porting Aegir to new platforms or installing on alien platform for which Aegir is not yet packaged.

System Requirements

Overview

A system capable of running Drupal

The Aegir system is entirely Drupal based, and has the same base requirements that Drupal does (with the exception that it won't run on Windows). See more notes on Unix and LAMP/LEMP requirements below.

Your own server

The low level of access required to be able to configure and run this system is very far beyond what is commonly available to users with shared hosting. A VPS from any popular provider such as Linode, Rackspace, Slicehost, Amazon EC, etc. will do fine.

LAMP / LEMP

LAMP / LEMP are used to run Aegir and provide the frontend interface, as well as provide those same tools to your managed sites. These components are further detailed in the following sections. While you can install Aegir alongside an existing LAMP installation, it is generally considered easier (and thus recommended) to start with a fresh server.

N.B.: If you do install Aegir alongside an existing server with LAMP/LEMP already configured, be aware that you will have to make configuration changes to Apache and MySQL where necessary, so that Aegir can work with your system.

A Unix-based operating system

Aegir must run on some flavour of UNIX, because the majority of functionality in this system occurs in the back-end, through command line scripting. There are also several features (such as symlinks), that are not available to users on Windows. There are no plans currently to add Windows support.

Web server

You will need at least one dedicated web server, running Apache. We generally work with Apache 2 but we should be compatible with the 1.x series. You will need root access to that server and the server must be reserved for Aegir. Sharing the server with other control panels such as Cpanel, Plesk or AlternC will very likely create problems and is not supported.

Aegir also supports Nginx web server, but requires at least version 0.7.27 or newer. Since Nginx doesn't provide php-cgi or php-fpm (recommended) modules, you will need to install and run php-fpm server separately. You can find useful examples and tips in the third party Barracuda installer available at http://gitorious.org/aegir/barracuda-octopus.

N.B.: This third party installer is not supported by the core Aegir developers, but you can find helpful community support at http://community.aegirproject.org.

Database server

You will require a database server, obviously. Aegir currently only supports MySQL and MariaDB. It is preferable to use a dedicated (not shared-hosting) server since Aegir will create database users and will require the use of the MySQL 'root' user.

PHP 5.2

PHP 5.2 and above is required to run Aegir because Aegir depends on Drush, which has this requirement. You also need to have the command-line version of PHP to run Drush properly and the MySQL extensions.

Note that Drupal's support for PHP 5.3 is still under development. Currently, using PHP 5.3 will cause (innocuous) warnings on every page load. As a result, we suggest using PHP 5.2 for the time-being.

See http://drupal.org/node/360605 (amongst other issues) for details.

Mail transfer agent

Aegir requires an MTA (Mail Transfer Agent) installed on your webserver in order to be able to install new sites to your new platform. If you don't have an MTA, the site installation will fail with message like "could not send email". Additional messages will show that site has been removed because of this problem. To remedy the situation simply install an MTA like sendmail, postfix, or exim and do the minimal configuration.

Other utilities: sudo, rsync, git and unzip

Aegir installs itself via a Drush Make makefile that downloads via git if you want the bleeding edge code, or via wget if you want the latest official release. If you want the latest development version, and don't have the git program you will need to install it on the server.

The jQueryUI library is used in the Aegir UI, unzip is required to extract it. Sudo is required to allow the aegir user the limited privilege to restart the webserver when required. Rsync is used to sync files to remote servers.

No conflicting Control Panels

Other popular control panels such as Plesk, cPanel etc, are designed to manage all aspects of Apache configuration and other areas that Aegir also is intended to be used for.

Running Aegir alongside such control panels is not supported and very likely may cause you problems or difficulties installing or running Aegir. This is not recommended. Filing bug reports that are caused by interference by another control panel may not get results. Proceed at your own risk / frustration!

System requirements of popular Drupal distributions

Some Drupal distributions, such as OpenAtrium, are specialised products that may contain unique prerequisites for optimal performance. Such examples may include raising the php-cli program's memory_limit to something higher than 64M.

Please note that this is not a requirement of Aegir but of the distribution you are trying to install a site on. Thus the Aegir documentation may not officially 'require' such performance settings, but be aware that Aegir may report errors if the system was under-resourced to complete such a task.

Install system requirements

To install the required components, run the following command as root:

apt-get install apache2 php5 php5-cli php5-gd php5-mysql postfix sudo rsync git-core unzip

Configure system requirements

Webserver configuration

Aegir supports two popular web servers, Apache and Nginx. At this time, Apache support is more stable, and recommended for most users.

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. In Debian-based systems, you should symlink this file inside /etc/apache2/conf.d that will be parsed on startup or alternatively you can place include that file in your apache.conf/httpd.conf. We prefer the former. In other systems there are similar ways to accomplish this. Consult your OS's documentation if unsure.

If you are on a Debian-based system, you will also need to enable the mod_rewrite module manually.

Run the following shell commands as root. First, configure Apache to enable RewriteEngine:

a2enmod rewrite

Finally, create a symlink from an apache configuration file to a folder within the /var/aegir/:

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

Do not reload/restart Apache if prompted to after running these commands, it will fail.

The installer script creates the configuration file referenced by the newly created symlink.

N.B.:

• A standard umask of 022 is assumed. This is the default on most systems.
• For more information, see the common installation errors.

Nginx configuration

(If you just succeeded in installing Apache, please skip this section.)

Aegir assumes standard Nginx configuration is 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. In Debian-based systems, you should symlink this file inside /etc/nginx/conf.d that will be parsed on startup.

Shell command as root::

ln -s /var/aegir/config/nginx.conf /etc/nginx/conf.d/aegir.conf

Do not reload/restart Nginx after running these commands, it will fail.

The installer script creates the configuration file referenced by the newly created symlink.

DNS configuration

Aegir requires a properly configured "FQDN" (Fully Qualified Domain Name) be assigned to the machine. In practice, this means that the hostname returned by the hostname and uname -n shell commands should resolve to the IP address for this server, and vice versa.

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.

You can add multiple entries to your /etc/hosts file for testing purposes, for example:

127.0.0.1 aegir.example.com example.com test1.example.com test2.example.com test3.example.com

Then you can use test1.example.com to create your first site.

PHP configuration

Some complex installation profiles or distributions require a PHP memory limit that is higher than the default. To avoid common errors when installing sites on some distributions, the PHP command line tool should be configured to use 192Mb of RAM.

Change the memory_limit directive in /etc/php5/cli/php.ini to read:

memory_limit = 192M      ; Maximum amount of memory a script may consume (192MB)

Most modern Drupal sites require around 96M or even 128M of RAM for certain operations. This is far more than what is provided by the default PHP configuration.

Change the memory_limit directive in /etc/php5/apache2/php.ini to read::

memory_limit = 128M      ; Maximum amount of memory a script may consume (128MB)

If your distributions require more memory than these limits, then use some common sense and update it as appropriate to suit your individual needs.

Database configuration

Aegir supports MySQL right now. It is best to install the MySQL server using your Linux distribution's package manager.

Shell commands as root::

apt-get install mysql-server

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.

Again, as root, edit the MySQL configuration file /etc/mysql/my.cnf configuration line to comment out by placing a # at the beginning of the line on which the following instruction appears::

bind-address    = 127.0.0.1

Without this line commented out, MySQL will listen only on localhost for database connection requests.

Now you need to restart mysql, to clear any caches.

Shell command as root::

/etc/init.d/mysql restart

The installer will prompt you for your MySQL root user password. The root user will be used to make administrative tasks such as creating new databases, and granting and revoking access to those databases for sites.

Even though MySQL is now listening on all IP's, it will not allow invalid users to connect to the databases, without the correct user accounts configured.

If you are concerned about MySQL being accessible in this way, you can also configure your firewall to only allow incoming connections from certain addresses. This is outside the scope of this document however.

Create the Aegir user

The provision framework of Aegir requires that the scripts run as a non-root system account, to ensure that it can correctly set the file permissions on the hosted files.

Also to ensure that the file permissions of the hosted sites are always as safe as can be, and especially to make sure that the web server does not have the ability to modify the code of the site, the configured system account needs to be a member of the web server group, in order to be able to correctly set the file permissions.

This document assumes the Aegir user is aegir, its home directory is /var/aegir and the webserver group is www-data. You can choose another username if desired.

In addition we will create a directory layout for Aegir configuration and backups.

Shell commands as root::

adduser --system --group --home /var/aegir aegir
adduser aegir www-data    #make aegir a user of group www-data

Sudo access

Next, we need to give the aegir user permission to execute the Apache2 command to restart the web server without entering a password.

For those using Apache, shell command as root::

visudo

This command opens an editor (which one depends on your OS flavor) to allow you to edit the /etc/sudoers file. Add the following to the end of the file (specific directions cannot be given since this depends on what editor you're using):

 aegir ALL=NOPASSWD: /usr/sbin/apache2ctl

Note - the path to your apache2ctl program may differ from this example. On some systems it may also be called 'apachectl' instead of apache2ctl. Adjust to suit your own requirements.

For those using Nginx, set the sudoer line as follows

aegir ALL=NOPASSWD: /etc/init.d/nginx

Install with install.sh

This section deals with the actual installation of Aegir using install.sh.

The install.sh script takes care of installing the right packages and preparing the backend and frontend for you. That script needs to be run as the aegir user created previously (see: Configure system requirements), so it needs to be placed somewhere that the aegir user can access in order to execute it. This file can be downloaded through the web with this shell command:

cd /var/aegir
wget -O install.sh 'http://drupalcode.org/project/provision.git/blob_plain/refs/tags/6.x-1.0-rc2:/install.sh.txt'

By default, the install script will install the "correct" version of Aegir (ie. if it was downloaded through git, it will install the version from the git master branch. If you downloaded an official release, it should install the official release.). You can modify which version to install by editing the AEGIR_VERSION variable in the script.

Shell command as 'aegir' user for Apache version:

su -s /bin/sh aegir -c "sh install.sh"

Shell command as 'aegir' user for Nginx version:

su -s /bin/sh aegir -c "sh install.sh --http_service_type=nginx"

Note you must run the above command as root or prefix with sudo.

You will be prompted for the information necessary to complete the installation.

Once you have run install.sh once, drush and provision should be installed.

Trouleshooting: You can use the more flexible hostmaster-install command to retry the install if it failed the first time (see: Complete the installation manually and Common installation problems).

Checkpoint / Finished!

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 (provision and drush). Your filesystem layout should look something like this:

 /var/aegir/hostmaster-1.x/
 /var/aegir/hostmaster-1.x/profiles/hostmaster/
 /var/aegir/hostmaster-1.x/profiles/hostmaster/modules/admin_menu/
 /var/aegir/hostmaster-1.x/profiles/hostmaster/modules/hosting/
 /var/aegir/hostmaster-1.x/profiles/hostmaster/modules/install_profile_api/
 /var/aegir/hostmaster-1.x/profiles/hostmaster/modules/jquery_ui/
 /var/aegir/hostmaster-1.x/profiles/hostmaster/modules/modalframe/
 /var/aegir/hostmaster-1.x/profiles/hostmaster/themes/eldir/
 /var/aegir/hostmaster-1.x/sites/aegir.example.com/
 /var/aegir/config/server_master/apache.conf
 /var/aegir/config/server_master/apache/conf.d/
 /var/aegir/config/server_master/apache/vhost.d/
 /var/aegir/config/server_master/apache/platform.d/
 /var/aegir/backups/
 /var/aegir/drush/drush.php
 /var/aegir/.drush/drush_make/
 /var/aegir/.drush/provision/

Variations on this are acceptable (for example, the Drush Debian package works out of /usr/bin/drush and that's fine), but you are better to stick with the defaults if you really want to get through this.

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.