This page describes to process you need to follow if Aegir doesn't have packages for your distribution. We currently provide Debian packages and others should be coming, if you help! This manual assumes you are fairly familiar with the UNIX commandline interface, but should be possible to follow through if you copy and paste faithfully all steps of the procedure.

A note on supported systems

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

It currently contains special recommendations for CentOS, RHEL 6, Arch Linux and Solaris. Users of those platforms are also strongly encouraged to review the common installation problems that occur on those platforms. Aegir is also known to be installable (and was developed partly on) Mac OS X, but that process is so obtuse that it has a separate page for the first part of the manual (up to Install Aegir components).

Installing Aegir may seem daunting at first (which is why we provide automated installs through packages), but once you get around it, it's fairly simple. It follows those steps:

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.

1. Review System Requirements

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. You will need root access to the server and the server needs to be dedicated to Aegir.

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. See the operating system support page for more information.

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. Aegir also supports the Nginx web server, but requires at least version 0.7.66 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 the barracuda project page.

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

PHP 5.2 and 5.3

Aegir depends on Drush 4.x, which requires PHP 5.2 or higher. Aegir 2.x depends on a minimun of Drush 5.10 (though Drush 6 is recommended), which requires PHP 5.3 or higher. You also need to have the command-line version of PHP to run Drush properly, and the MySQL extensions for PHP.

Given that PHP 5.2 has been deprecated since July 2010, we suggest using PHP 5.3 if possible. Note that while Drupal 6.x and above support PHP 5.3, some contributed third-party modules may still have problems with this version. Most often these cause warnings that can be safely ignored. Aegir and Drush themselves have no known outstanding PHP 5.3 compatibility issues, although you could have a lot of warnings in Drupal 6 due to ereg deprecation, see this issue for details. If you need to host Drupal 5.x sites, note that Drupal 5.x is not compatible with PHP 5.3 and above, and most likely never will be. See http://drupal.org/node/360605 (amongst other issues) for details. As such, Aegir has dropped support for Drupal 5 in versions 2.0+.

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 a MySQL root user.

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. Filing bug reports that are caused by interference by another control panel will likely be closed unless the problem can be fixed without causing problems for other Aegir users. Proceed at your own risk!

System requirements of popular Drupal distributions

Some Drupal distributions, such as OpenAtrium, are specialized 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.

2. 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 php-pear postfix sudo rsync git-core unzip

Note: replace apache2 with nginx php5-fpm to install nginx on Ubuntu Precise or newer. Since Debian Squeeze doesn't provide php5-fpm, you will need to follow http://www.dotdeb.org/instructions/ before you will be able to install php5-fpm.

2.1. CentOS-specific configuration

yum install httpd php php-mysql php-cli php-gd php-process sudo rsync git postfix

For versions of CentOS previous to 6.0, you will need to upgrade to PHP 5.3 using those instructions.

Also for Centos minimal you should install cron (for queue and drupal cron) and unzip (for jquery.ui)

yum install cronie unzip

2.2. RHEL 6 specific configuration

RHEL 6 Server needs an additional PHP package to enable POSIX support. To find the package php-process you must enable the RHEL Server Optional channel. Once enabled, download and install the php-process-5.3.2-6.el6_0.1.i686.rpm.

You will also need to install the php-xml package if you are planning to use Aegir to manage Drupal 7 sites.

2.3. Solaris specific configuration

Solaris has this way of dealing with third party software that is... far from ideal. You will need to find the best way to install the following packages: apache2, git, sudo, mysql, PHP 5.2 and wget. unzip and sendmail should be part of the base Solaris install. The other applications should be available on the companion CDs or on sunfreeware.com.

In particular, git can be compiled easily by exporting the following environment::

export CFLAGS="-I/usr/sfw/include -I/opt/sfw/include"
export LD_LIBRARY_PATH="/usr/sfw/lib:/opt/sfw/lib:$LD_LIBRARY_PATH"

Then the compile instructions bundled with git should just be followed directly. I had trouble installing the binaries, as git expects ginstall to be available in the $PATH. I ended up adding the source directory in the $PATH, which works fine for most uses.

2.4. Arch Linux specific configuration

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

pacman -S apache php php-apache php-gd mysql postfix sudo rsync unzip git

Although all of the necessary apache modules and php extensions are installed at this stage, further configuration is required to enable and tweak certain features. Critically, virtual hosts are not enabled. It is worth examining the Arch Linux wiki page on LAMP server set up and verifying that more than one named virtual host functions properly.

If setting up for standalone development, see this useful wiki page to configuring postfix for local mail only.

To ensure Apache and mysql start when the machine boots, enable the httpd and mysqld daemons by adding them to the /etc/rc.conf file:

DAEMONS=(... mysqld httpd ...)

3. Configure system requirements

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

While you can choose another username, most aegir documentation assumes the Aegir user is aegir, its home directory is /var/aegir and the webserver group is www-data.

Shell commands as root:

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

3.1.1. CentOS specific configuration

CentOS requires special commands to create the user, use those instead:

useradd --home-dir /var/aegir aegir
gpasswd -a aegir apache
chmod -R 755 /var/aegir

3.1.2. Solaris specific configuration

groupadd aegir
useradd -g aegir -G webservd -d /var/aegir -s /bin/bash -c "Aegir sandbox" aegir
chown aegir:aegir /var/aegir

3.1.3. Arch Linux specific configuration

useradd --system --groups http --home /var/aegir --create-home aegir
chmod -R 755 /var/aegir

3.2. Webserver configuration

Aegir supports two popular web servers, Apache and Nginx.

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

3.2.1.1. CentOS specific Apache configuration

On CentOS, mod_rewrite is enabled by default and you can create the following symlink:

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

3.2.1.2. Arch Linux specific Apache configuration

On Arch Linux, mod_rewrite is also enabled by default. Add the aegir apache configuration include file to the httpd.conf file:

echo "Include /var/aegir/config/apache.conf" >> /etc/httpd/conf/httpd.conf

3.2.1.3. Other systems' Apache configuration

In other systems that do not have a conf.d directory, this could also work:

echo "Include /var/aegir/config/apache.conf" >> /etc/apache2/httpd.conf

N.B.:

• A standard umask of 022 is assumed. This is the default on most systems.
• For more information, see the common installation errors.
• For all OSes, the installer script creates the configuration file referenced by the newly created symlink/or file referenced in the Apache config file.

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

Please make sure your nginx installation is up and running before continuing. On Ubuntu 12.04 Server, for instance, you must edit /etc/nginx/nginx.conf and uncomment the line "types_hash_max_size 2048;" in order for nginx to start successfully.

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.

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

3.3.1. RHEL 6 specific configuration

The default php.ini configuration beyond the above changes also requires that the timezone be set for your location. Otherwise, you get fun errors and warnings during the host-master install step.

1. sudo vi /etc/php.ini
2. enter your password
3. /zone (this will bring you to the date specific timezone module area

4. Remove the semi colon in front of date.timezone and enter your specific timezone.

   [Date]
  ; Defines the default timezone used by the date functions
  ; http://www.php.net/manual/en/datetime.configuration.php#ini.date.timezone
  date.timezone = Your Time Zone Goes Here

5. Restart apache to compile these changes. sudo httpd -k graceful

3.3.2. Arch Linux specific configuration

Make the following changes to the php.ini file (/etc/php/php.ini):

Add :/var/aegir/ to the open_basedir directive:

open_basedir = /srv/http/:/home/:/tmp/:/usr/share/pear/:/var/aegir/

Add date.timezone value as per PHP's runtime configuration instructions - this is an example:

date.timezone = Europe/London

Modify the memory_limit directive:

memory_limit = 192M

Uncomment

extension=posix.so
extension=mysqli.so

3.4. Sudo configuration

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

Create a file at /etc/sudoers.d/aegir and add the following:

Defaults:aegir  !requiretty
aegir ALL=NOPASSWD: /usr/sbin/apache2ctl

After saving, change the permissions on the file:

chmod 0440 /etc/sudoers.d/aegir

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.

3.4.1. CentOS Linux specific sudo configuration

For CentOS apache2ctl is apachectl and you should use this instead, as root::

visudo

This command opens an editor 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):

Defaults:aegir  !requiretty
aegir ALL=NOPASSWD: /usr/sbin/apachectl

Note - the !requiretty bit is to make aegir able to run sudo even though it's not attached to a terminal. By default CentOS enforces requiretty so this exception is necessary.

3.4.2. Nginx specific configuration

For those using Nginx, set the sudoers line as follows

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

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

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

Note that Aegir will ask you for your MySQL root password. If you do not want to use your regular root password for Aegir, you will need to create another root account for Aegir using a MySQL command like:

GRANT ALL PRIVILEGES ON *.* TO 'aegir_root'@'%' IDENTIFIED BY 'password' WITH GRANT OPTION;

Note: If you are running your Aegir databases on a remote DB server, you will want to create this aegir_root user. The install will often fail if you're trying to use the root user on a remote database. See this issue for details.

3.6.1. Ubuntu, RHEL, Arch linux specific configurations

NOTE: If you are running either Ubuntu 12.04 LTS, RHEL 6 or Arch Linux, you should still install MySQL in the same way as above. However, once done, you must now remove the anonymous, passwordless login that those platforms creates by default. To do this, run:

sudo mysql_secure_installation

Otherwise, Aegir will fail to install and work at all. See this FAQ entry.

3.6.2. RHEL 6 specific configuration

In Red Hat, you may need to move a default configuration file from /usr/share/mysql/ to /etc/my.cnf to view or modify any of the settings mentioned above.

4. Install Aegir components

Next step is to install the Aegir software components themselves, that is: drush, provision and hostmaster.

4.1. Install drush

Before installing Aegir proper, you first need to install Drush. This can be done through your operating system's package manager (Drush is shipped with Debian and Ubuntu currently) or by following the Drush README.txt file which has all the information for installing and using drush.

This should be something like:

pear channel-discover pear.drush.org
pear install drush/drush-4.5.0

Note: you should use Drush version 4. Aegir 1.x does not support Drush 5, although 2.x does. Also note there is a bug in Drush 4.0 and 4.1 so you should use a version of Drush between 4.1 and 5.

This should install Drush system-wide, but if you follow the manual install, you may end up with Drush in a non-standard location (traditionnally /var/aegir/drush/drush.php), in which case you will need to add that directory to your path or use the following symlink:

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

Note for 2.x users: you need to install Drush version 5. In this case, you may be able to install the regular release:

pear channel-discover pear.drush.org
pear install drush/drush

4.1.1. Arch Linux specific configuration

It seems that Arch's PHP environment needs to be modified for Drush:

mkdir /var/aegir/.drush
cp /etc/php/php.ini /var/aegir/.drush/

Edit /var/aegir/.drush/php.ini to remove the values after open_basedir =, as this will any open_basedir values are likely to cause Drush to fail.

4.2. Stop! Now become the Aegir user!

The remaining of this manual assumes you are running as the Aegir user. Things will go very wrong if you do not change your shell credentials to become that user. You can do this by running the following command as root:

su -s /bin/bash - aegir

If this fails because /bin/bash doesn't exist, try using /bin/sh.

4.3. Install provision

Once Drush is installed you should be able to install the latest recommended Provision release using the following drush command:

drush dl --destination=/var/aegir/.drush provision-6.x

To download a different version of provision, use this:

drush dl --destination=/var/aegir/.drush provision-6.x-2.0-rc2

Note: the above will install the 2.0-rc2 release of Aegir, which is the development release of Aegir, and is not considered production ready!

4.4. Running hostmaster-install

Once you have downloaded drush and provision, you can just install provision in the commands directory of Drush (either ~aegir/.drush or /usr/share/drush/commands), if that's not already done. Once provision is properly installed, you can install all other aegir components using the hostmaster-install command:

drush hostmaster-install

You will be prompted for the required information if not provided on the commandline. See the inline help for the available options:

drush help hostmaster-install

For example, to install the frontend on Nginx, use:

drush hostmaster-install --http_service_type=nginx

Note for 2.x users: Drush 5 has a commandfile cache which you need to clear before installing Aegir:

drush cache-clear drush

It is imperative that you provide a valid FQDN to the installer. This is used for database GRANTs. Remote web servers depend on the FQDN being resolvable in order to connect back to your Aegir master server if it is used as your database server for managed sites.

Upon completion of the installation, the traditional Drupal 'Welcome' e-mail will be sent to the e-mail address specified by --client_email=(your e-mail) or if not provided as a command line switch, the address prompted by the installer process. This e-mail address will also be used as the default e-mail address of the first user and client in Aegir, but can be changed later.

There are other commandline switches available, documented in drush help hostmaster-install, as usual.

4.4.1. Arch Linux specific configuration

drush hostmaster-install --web_group=http

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

For troubleshooting this process and resulting install, see the common installation problems page.

You may also want to read on with what you can do with Aegir now that it is installed.