Note that the following System Requirements are the same for Aegir automatic or manual install

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.

These are the installation instructions that are recommended on Debian. Aegir dependencies (Apache, MySQL, PHP...) are also automatically installed. If you are managing the installation from a remote Windows computer, well-known open source tools for this task are for example PuTTY (a SSH client for command line), and WinSCP (a SFTP client with easy text file editing).

If you wish to install Debian packages over an existing manual install, it's possible. See the Debian upgrade procedures.

Debian packages are uploaded to http://debian.aegirproject.org/ shortly after a release. We eventually want to upload those packages to the official archives, but this will take some adaptation and time to sponsor the packages in.

1. Requirements for automatic install on Debian

Basic Linux system administration skills

Root access to your server

An up-to-date system and applications

Run the following command lines to update your system and applications.

  aptitude update
 

  aptitude safe-upgrade
 

A configured Fully Qualified Domain Name (FQDN)

Such as aegir.example.com

The hostname returned by the commands hostname -f and uname -a must resolve to the IP address of your server.

After setting up your FQDN you must restart your server with a reboot command so your changes take effect.

Note that newly created domain name usually take 24 to 48 hours to fully start working. This period, called propagation, is the projected length of time it takes for root name servers and cache records across the entire web to be updated with your website's DNS information.

Other System Requirements

Find http://community.aegirproject.org/content/installing/system-requirements

2. Adding the project repositories

Use this command to add the Aegir package "Software Source" repository to your system:

To install a customized Debian package, see the developer instructions for the debian package. Other distributions are available for courageous people that want to try development versions.

2.x note: to install the development version of Aegir, you can use the unstable or stable distribution above.

3. Adding the archive key to your keyring

This repository self-signs packages uploaded to it (and packages uploaded are verified against a whitelist of trusted uploaders) using OpenPGP (GnuPG, to be more precise).

Use these commands to download and add the repository's PGP key, then update the package list on your system:

4. Adding backports for or manually installing Drush

If you are running Debian wheezy or later, or Ubuntu Natty 11.04 or later, you don't need to do anything here. The Drush package you need is available from your distribution's repositories.

If not, you should also configure backports repositories for Drush. Version 4.4 of Drush is now in Debian unstable, wheezy, squeeze-backports and Ubuntu Natty.

1.x note: if you are running Debian Squeeze 6.0 or Debian Squeeze 7.0, add the following line to /etc/apt/sources.list :

You might also have to add a proper Pin-Priority before this works. Create a file called drush containing the following and drop it into /etc/apt/preferences.d:

Alternatively, you could download and install the squeeze-backports package for Drush 4.5 directly from: http://packages.debian.org/squeeze-backports/all/drush/download. Then you could install it with:

dpkg -i drush_4.5-2~bpo60+1_all.deb

2.x note: if you are running Debian Squeeze 6.0, to get drush-5.8.x and above, download php-console-table manually and install it

You do not need to edit /etc/apt/sources.list or create /etc/apt/preferences.d/drush

Then run:

If you are running Debian lenny 5.0 or Ubuntu Maverick 10.10 or Karmic Koala or earlier, we recommend downloading and installing the Drush package manually. The version of Drush in the Ubuntu Universe repository for these versions of Ubuntu is outdated. If you are using Ubuntu Lucid LTS 10.04, you can install the Drush package manually or instead use Brian Mercer's PPA (Personal Package Archive) using the following command:

Now run apt-get update again to refresh the apt database.

N.B. Since Aegir 2 requires Drush 5, which in turn requires PHP 5.3+, Drupal 5 sites are not supported in Aegir 2.

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 -f and uname -n shell commands should resolve to the IP address for this server, and vice versa, with the resolveip command (included with the mysql-server package).

For Ubuntu, /etc/hosts should have entries that look like:

To set this up in a virtual machine (e.g. Virtualbox), here are the steps:

1. Create a new VM
2. Go to settings->network. Enable Adapter 2, and set to "host-only"
3. Install Ubuntu. Set hostname as FQDN during install
4. You may need to add the lines `auto eth1` and `iface eth1 inet dhcp` to /etc/network/interfaces

If you have a virtual machine already setup and want to change the FDQN:

1. change /etc/hostname using: `sudo hostname NEW_NAME`
2. change /etc/hosts using: `sudo nano /etc/hosts` and change name
3. reboot and test `hostname -f`, `uname -n`, `resolveip NEW_NAME`, `resolveip IP`
4. YMMV - Your Mileage May Vary

6. Manual sudo configuration

If you are running Debian squeeze or later, or Ubuntu Lucid 11.04 or later, you don't need to do anything here. The Aegir package configures sudoers automatically.

If not, you will need to manually modify your /etc/sudoers file to add the following line:

The line above assumes that you have created a user aegir as specified in the installation instructions.

7. Manual installation of MySQL (on Ubuntu 12.04 LTS)

Please note that Ubuntu 12.04 LTS installs, by default, an insecure MySQL installation that contains an anonymous user grant, allowing anyone to login without a password. This breaks Aegir functionality.

If you are running Ubuntu 12.04, you should install MySQL manually, and then ensure it is installed securely:

When running 'sudo mysql_secure_installation', answer 'Y' to 'Remove anonymous users?'

Now you can proceed with installing Aegir below.

8. Installing Aegir

To install Aegir version 2, frontend and backend, use the following command:

2.x note: Aegir version 2 is now stable. Read more at http://community.aegirproject.org/2.1

1.x note: to install Aegir version 1, use sudo apt-get install aegir instead.

If apt-get reports that the aegir packages have unmet dependencies, then make sure that you have installed Drush (as explained above). On a debian system, you can force the install of Drush from the squeeze-backports repository:

Then install aegir using the apt-get command above.

This will prompt you for the required information (MySQL password, Postfix configuration...) and go ahead with the install.

During the Postfix configuration, the following options appear: "No configuration, Internet site, Internet with smarthost, Satellite system, Local only". That first text screen only allows to use the tab key to select "OK", and then the enter key to display a second screen where you can select one of the choices. The default is "Internet site", useful in most cases to enable the server to send email messages, for example to the admin.

At the end of the installation, you will receive an email message or, if the user "aegir" has been assigned with a local email account during the installation, the file /var/mail/aegir will contain the message. It will include a one-time login to your new Aegir control panel, that is a URL to copy into your browser so that you can set the password for the "admin" user.

9. Custom Drupal distributions and make files

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

echo debconf aegir/makefile string /var/aegir/makefiles/aegir/aegir-custom.make | debconf-set-selections
apt-get install aegir

This allows you to specify the makefile path for your custom distribution of Aegir. To maintain these customizations, you'll need to ensure you do the same when upgrading.

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

Note that for this to work, you may need the patch from this issue, allowing drush_make to reference absolute system paths. If drush make --version <= 2.2 you need this patch.

After installing Aegir, you can reinstall the front end (hostmaster), with following commands:

su -s /bin/sh aegir -c "some command" runs some command in the /bin/sh shell as user aegir. sudo runs the su command as root - prompting for your user's password instead su asking for aegir's password.

10. Troubleshooting the install

To make the install smoother, the install command is run without much debugging information, which can make diagnostics pretty hard. For this, there's a special environment variable you can set that will trigger debugging output. Install aegir with this*:

You can build your own Debian packages from our repositories using those instructions.

Note: Prior to 1.1-4. the command was env DEBUG=yes apt-get install aegir

Here are simplified instructions for installing Aegir on a server, quickly and easily.

The fastest way to install Aegir is on the latest Ubuntu Server LTS (Long Term Support). Currently 12.04.

Command Summary

Here is every command, ready to copy and paste.

It is highly recommended to read through the Installation Instructions step by step to give yourself the feel for how this is done. In addition, if you are not already familiar in Linux system administration, please read up on the subject. Standard linux security protocols should be followed.

Installation Instructions

Enter all commands in code boxes exactly as they are written.

ALL commands should be entered as root user until these instructions are complete. After that, you should never have to use the root user.

Self-installation of Ubuntu has you create an additional user in the admin group, which means they can sudo. If you are using a cloud hosting service, it likely just sent you root user credentials. Server security and user management is up to you. Don't give away access to root or the aegir user unless you know what you are doing. Follow standard web host best practices

For a summary of all needed commands, scroll to the bottom of the page.

1. Fire up a new server

   • Use Ubuntu 11.04 Server Edition for the smoothest and most reliable installation experience.
   • Make sure it has at least 1024MB, preferably 2048MB of memory. Depending on your host you will have to configure a hostname. It can be convenient to call this 'aegir'.
   • If you want the smoothest installation, create a brand new server. There will be the least chance of conflicts if you start with a brand new Ubuntu 11.04 server. If you use Ubuntu Desktop, you should be able follow these instructions without any problems.
   • Run all commands as root. If you are not root, enter
     sudo su

2. Add the project repositories and archive key

   Use this command to add the Aegir package "Software Source" repository to your system:

   echo "deb http://debian.aegirproject.org stable main" | tee -a /etc/apt/sources.list.d/aegir-stable.list
   Use this command to add the archive key to your keyring:
   wget -q http://debian.aegirproject.org/key.asc -O- | apt-key add -
   Then, finally, update your apt repositories:
   apt-get update

3. Install configure Aegir and dependencies

   Once you have added the repositories, you can now fire off the standard debian installation command. For Aegir 1.x, the command is:

   apt-get install aegir
   For Aegir 2.x, the command is:
   apt-get install aegir2
   This fires off the installation script for AEgir, along all dependencies including Apache, MySQ and PHP. You will be asked a number of questions about your server.
   • You will be asked to create a MySQL root user password. Make this long and random and type it down somewhere safe, you won't need it very often, but you will need it later on in the installation process.
   • In Postfix Configuration: Choose Internet Site, unless you have a reason otherwise. When asked for the System mail name, pick either the hostname (default) or the domain name you will be hosting this server on.
   • In Configure aegir-hostmaster, you will be asked to choose a "URL of the hostmaster frontend". This should be either the hostname (default) or the domain name the server will be hosting, with "aegir" as a subdomain. For example, "aegir.example.com". You may want to change this to whatever you prefer, just don't forget it as it will be where you use the Aegir front-end.
   • After entering your domain, Aegir Hostmaster installation will ask you for the MySQL root password you created earlier. You did write it down, didn't you?
     NOTE: The current DEB package requires you to enter the MySQL root password twice. When this script is done, if everything went ok, after a lot of other interesting information, you should see this:
     Aegir is now installed. You can visit it at http://test/user/reset/1/1329504351/eda205d9a27abde400a27cf160dff69a
***... frontend bootstrap correctly, operation was a success!
Setting up aegir (1.6-1) ...
Setting up libhtml-template-perl (2.9-2) ...
Setting up mysql-server (5.1.54-1ubuntu4) ...
Setting up php5 (5.3.5-1ubuntu7.7) ...
Processing triggers for libc-bin ...
ldconfig deferred processing now taking place
root@test:~#

   At this point, everything is installed. Visit the link the script provided you to check out the frontend. Switch to the aegir user to check out the backend:

   su - aegir

   Once you are the aegir user, check out the drush site aliases it gives you. @hostmaster is the alias for the new front-end you created. You will get new site aliases for every platform and site you create.

   drush site-aliases

4. Give yourself access to the server

   As the "Administrators Manual" can tell you, you should only manage the Aegir server from the backend as the aegir user.

   However, by default, the aegir user cannot sudo (except to restart apache). The aegir user also does not have a password. Therefor, the only way to become aegir is to sudo su - aegir from a user that can.

   So, to finish the server, you should give yourself a personal account that you can use to login to the server with a password in case all of your SSH keys get lost.

   To add yourself as a user:

   adduser yourname
   Then fill out the little wizard it gives you.

   //@TODO: Add some helpful notes about SSH keys and remote aliases.

   Install SSH on your server, generating your SSH keys and install them on your Ubuntu server. (Directions to generate your SSH keys are assuming your PC is Ubuntu as well, Windows users look below for SSH directions)

   • Tutorial: https://help.ubuntu.com/11.04/serverguide/C/openssh-server.html

   If using Windows, you must use Putty, PuttyGen, and PuttyPageant to generate and use your SSH keys.

   • Tutorial #1: http://the.earth.li/~sgtatham/putty/0.53b/htmldoc/Chapter8.html
   • Tutorial #2: http://www.howtoforge.com/ssh_key_based_logins_putty

   You will want to also be a part of the aegir and www-data groups so you can write to some of their files:

   addgroup yourname aegir
addgroup yourname www-data

5. Start Using!

   Now that aegir is installed, head to the User Manual page to get your first platform and site up and running.

Credits

This document was originally based on http://community.aegirproject.org/installing/debian but has been trimmed down to list only the steps you need to use on an Ubuntu server to get Aegir up and running as quickly and easily as possible.

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

Find http://community.aegirproject.org/content/installing/system-requirements

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  

3.2.1.1. Ubuntu 14.04+ specific Apache configuration

Ubuntu 14.04 departs from Debian and previous Ubuntu Apache setup in that it doesn't use /etc/apache2/conf.d any more and better separates out sites-enabled from conf-enabled configurations. So:

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

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

3.2.1.2. 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.3. 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.4. 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.

For Aegir 3, make sure you've installed the required PHP extensions, particularly the image library (php-gd).

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 as follow:

Before

bind-address        = 127.0.0.1

After

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

Note for 1.x users: you should use Drush version 4. Aegir 1.x does not support Drush 5. 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.

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

Note for 2.x users: you need to install a minimum of Drush version 5.10, though Drush 6.x is recommended. In this case, you may be able to install the regular release:

Note for 3.x users: you need to install a minimum of Drush version 6,some time you need apt-get install php-console-table before you become the Aegir user:

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

This should install Drush system-wide, but if you follow the manual install, you may end up with Drush in a non-standard location (traditionally /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

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:

Note for 1.x users:

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

Note for 2.x users:

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

Note for 3.x users: replace provison-6.x-2.0 to provison-7.x

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. Install the Hosting Queue Daemon

For Aegir 2.x installs, using the Hosting Queued Daemon (hosting_queued) is highly recommended. For Aegir 1.x, check out http://drupal.org/project/hosting_queue_runner instead.

These instructions will install the daemon to run as a regular service in /etc/init.d/. Instructions will vary according to platforms, but the following should work in Debian, running as root.

1. Install the init script in place

   cp <hostmaster_platform_root>/profiles/hostmaster/modules/hosting/queued/init.d.example /etc/init.d/hosting-queued
   

2. Setup symlinks and runlevels

   update-rc.d hosting-queued defaults
   

3. Start the daemon

   /etc/init.d/hosting-queued
   

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

Apache

For Apache based installation hints see Apache / mySQL / PHP / Aegir

Nginx

Nginx is more performant than Apache, if you are interested in setting Aegir up using nginx Brian Gilbert from Realityloop has created a script to install everything that you need on a clean Mac (not already running anything on port 80), see OSX Aegir Installer on github.

This is a helper file to the canonical manual install process. It is aimed at helping you install Aegir on Mac OS X. Since PHP and MySQL support on OS X is fairly limited and complicated, a separate documentation page was created for that part of the documentation. You should follow this page all the way through and then proceed with the regular install, step 4: becoming the aegir user.

1. Special software requirements

While Mac OS X comes with Apache & PHP (and even MySQL on the Server version), the version of PHP shipped with 10.6 Snow Leopard is 5.3.x and thus may not work with Aegir (as of the 0.4alpha-era) and various other software. If you're running 10.5 Leopard, it may work out of the box, but I haven't tested it.

There are several different ways to get Apache, PHP 5.2, and MySQL 5 onto a Mac OS X machine. I give detailed instructions for MacPorts below, but if that's a bit more than you're ready to bite off right now, feel free to use an alternative approach.

One such alternative is MAMP. There is a good but outdated HOWTO for installing Aegir on Mac OS X 10.6 (Snow Leopard) using MAMP located here: http://groups.drupal.org/node/30270

MAMP stands for Mac, Apache, MySQL, and PHP and is the Mac equivalent of "LAMP". It is a self-contained package of all of these programs with a nice graphical installer and control panel. You can find it here: http://www.mamp.info/

MAMP is pretty straightforward, but it's also not very flexible (IMHO). While certainly not without its own headaches, MacPorts is a decently powerful way to sanely manage a healthy stack of open source UNIX software on your Mac. Since this is what I use, I'm going to assume MacPorts is in use for the rest of this HINTS file. I have also only tested this on Mac OS X 10.6 Snow Leopard.

If you don't yet have MacPorts installed, go here to get it: http://www.macports.org/install.php

Once it's installed, quit and re-launch your Terminal before continuing. Otherwise MacPorts won't yet be in your PATH.

The first two commands below are optional but recommended.

php5-apc is optional, but highly recommended as it will significantly increase PHP performance.

Watch the output of the last port command carefully, as there are usually some boring tasks for you to perform once the install is done. You'll be wishing you were running Ubuntu/Debian and apt-get by the time you're done.

2. Configure system requirements

Next we'll create the aegir user and add it to the _www group. This part is very different on Mac OS X than Linux or most other Unices. Must be a NeXTism. The command we will use he is "dscl", which is a short for Directory Service Command Line. In OSX 10.3 and earlier, that command is "nicl" (short for Net Info Command Line). It is also possible to create the user using the "Workgroup Manager" utility included with OS X Server. To obtain Workgroup Manager for the OS X Client, download the "Server Admin Tools" from Apple. For example, for Mac OS X 10.6, the admin tools can be found at:

http://support.apple.com/downloads/Server_Admin_Tools_10_6

Now you need to find the next spare UID to assign the user.

Here's how you find out on your system:

Then open the file users.out in a text editor, search for the highest 5xx user ID and add 1 to it (in your brain, not in the file). So if you find 506 but no 507, use 507. When you're done, delete users.out to be safe.

Now assign this UID to the aegir user, replacing "5xx" with the UID.

!! If you're running Mac OSX Lion, you also need to assign PrimaryGroupID to the aegir user.
   sudo dscl . -create /Users/aegir PrimaryGroupID XXX

Set a secure password for the aegir user, as it needs shell access.

Create the aegir home directory and set its permissions.

Add the aegir user to the _www group. This is the group Apache runs as.

Give the aegir user the ability to restart Apache.

Go to the last line of the file and add the following.

Save the file and exit your text editor.

Next configure Apache to include the Aegir config.

Configuring your MySQL database and user accounts is the same as in the INSTALL.txt file. But you probably want to add the path to its executables to your user's PATH and the aegir user's PATH.

The instructions that used to be here are now outdated, instead use the OSXAegirInstaller created by Brian Gilbert of Realityloop.

There are 2 methods of installing AEgir on CentOS both are the same but one is scripted and the other is manual and is documented below.

Scripted

The script can be found at https://github.com/marafa/aegir/tree/master/version2

NB. There is preliminary work to fix selinux at https://github.com/marafa/aegir/blob/master/aegir_selinux.sh. Feedback is quite welcome as well as git pulls.

Explanation

Connect to the server via ssh as root user.

ssh root@000.000.000.000

Install system requirements

yum install httpd php php-mysql php-cli php-gd php-process php-pear php-mbstring php-xml php-soap sudo rsync git postfix tree wget cronie unzip mysql-server mlocate nmap samba samba-client samba-common vim

Note: The following packages are not required but are very useful to include git wget mlocate nmap samba samba-client samba-common vim

SElinux

Make sure Security-Enhanced Linux is disabled as it creates install problems.

vim /etc/selinux/config Make sure SELINUX=disabled

If was SELINUX=enabled then we need to restart.

shutdown -r now

Note: I am not sure if it can be enabled at the end I have never tried.

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.

useradd --home-dir /var/aegir aegir

gpasswd -a aegir apache

chmod -R 755 /var/aegir

Apache configuration

Start Apache

service httpd start

Make apache start automatically after reboot.

chkconfig httpd on

We need to create a symbolic link between aegir and apache.

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

PHP configuration

vim /etc/php.ini

Increase the memory limit as complex installation profiles or distributions require a PHP memory limit that is higher than the default (128M)

memory_limit = 192M

Set Date Zone to your time zone see http://www.php.net/manual/en/datetime.configuration.php#ini.date.timezone

date.timezone = “”

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.

visudo

Add to end of file

Defaults:aegir !requiretty

aegir ALL=NOPASSWD: /usr/sbin/apachectl

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:#> >vim /etc/hosts Add your ip and hostname

000.000.000.000 hostname

Database configuration

Start mysql

service mysqld start

Make mysql start automatically after reboot.

chkconfig mysqld on

Configure Mysql

/usr/bin/mysql_secure_installation

Recommended:

Set root Password

Remove anonymous users? y

Disallow root login remotely? y

Remove test database and access to it? y

Reload privilege tables now? y

Install drush

pear channel-discover pear.drush.org

pear install drush/drush-4.5.0

Check if drush works If you get PHP Fatal error: Class 'Console_Table' not found then

pear install Console_Table

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.

su -s /bin/bash - aegir

Install provision

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

Clear the drush cache

drush cache-clear drush

Run hostmaster-install

drush hostmaster-install

These are some really rough notes on how to go about creating a 4 server aegir installation (aegir, mysql, web1, web2).

Adapted from reading through the BOA project and my own experimentation.

** Note -- regarding the wildcard SSL, your sites will need some configuration in your settings.php or local.settings.php to check for the X-Forwarded-Proto headers. I can't recall if the wildcard SSL config.

These notes also assume the last Ubuntu LTS -- 10.04/Lucid.

aegirmysql:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install vim mysql-server


_USER="aegir"
_DOMAIN="aegir.domain.com"
_AEGIR_HOST="aegir.server.hostname"
_AEGIR_HOST_IP="123.456.789.01"
_AEGIR_PASSWORD="password"

#AEGIR_DB_USER=aegir_root
#AEGIR_DB_PASS=`echo $RANDOM:\`date\`:$AEGIR_HOST | openssl md5`

echo "[client]
user=root
password=password" >> .my.cnf

mysql -uroot mysql<<EOFMYSQL
GRANT ALL PRIVILEGES ON *.* TO '$_USER'@'$_DOMAIN' IDENTIFIED BY 'password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO '$_USER'@'$_AEGIR_HOST' IDENTIFIED BY 'password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO '$_USER'@'$_AEGIR_HOST_IP' IDENTIFIED BY 'password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO '$_USER'@'localhost' IDENTIFIED BY 'password' WITH GRANT OPTION;
FLUSH PRIVILEGES;
EOFMYSQL


========================

# https://launchpad.net/~brianmercer/+archive/nginx
# https://launchpad.net/~nginx/+archive/php5

aegircontrol:

sudo apt-get update
sudo apt-get upgrade

sudo mkdir -p /var/www/nginx-default

#php5-suhosin
CATHOSTDEBDEPS="git-core git-doc mysql-client-5.1 vim nginx-custom drush postfix php5-cli php5-mysql php5-fpm php5-gd rsync unzip bzr patch curl"
sudo apt-get -V install $CATHOSTDEBDEPS

#postfix config already sorted

sudo adduser --system --group --home /var/aegir aegir
sudo adduser aegir www-data
sudo chsh -s /bin/bash aegir

#patch drush, re: ereg()

#as root:
echo "aegir ALL=NOPASSWD: /etc/init.d/nginx" >> /etc/sudoers

ln -s /var/aegir/config/nginx.conf /etc/nginx/conf.d/aegir.conf
#disable directives in nginx.conf:
#types_hash_max_size
#tcp_nopush
#error_log
invoke-rc.d nginx restart

#install SSL cert to:
/etc/ssl/private/domain.com.cert.pem
cd /etc/ssl/private/
ln -s domain.com.cert.pem nginx-wild-ssl.crt
ln -s domain.com.cert.pem nginx-wild-ssl.key

#install SSL config to:
/var/aegir/config/server_master/nginx/pre.d/nginx_wild_ssl.conf
#TODO: also install for /var/aegir/config/server_aegirweb{1,2}.host.name

#as aegir:
cd ~

mkdir .ssh
ssh-keygen -t rsa

ln -s /usr/share/drush /var/aegir/drush
mkdir ~/.drush
cd ~/.drush
wget -c http://ftp.drupal.org/files/projects/provision-6.x-1.3.tar.gz
tar -zxf provision-6.x-1.3.tar.gz

#htaccess password bit
mkdir ~/tmp
cd ~/tmp
git clone --branch develop git://github.com/computerminds/aegir_http_basic.git
#must be develop branch to use crypt() and for nginx support
cp -r aegir_http_basic/provision ~/.drush/provision/aegir_http_basic
cp -r aegir_http_basic/hosting ~/hostmaster-6.x-1.3/profiles/hostmaster/modules/hosting/http_basic_auth
#set directory permissions? -- patch aegir/http_basic module to do so?

_DOMAIN="aegir.domain.com"
_USER="aegir"
#_AEGIR_HOST=`uname -n`
_AEGIR_HOST="aegir.server.hostname"
_AEGIR_HOME="$HOME"
_AEGIR_DB_PASS="password"
_AEGIR_DB_HOST="mysql.server.fqdn"
_AEGIR_VERSION="1.3"
#_AEGIR_ROOT="$_AEGIR_HOME/hostmaster-$_AEGIR_VERSION"
_ADM_EMAIL="admin@domain.com""
_WEBG=www-data
_USRG=users

#going vanilla
echo "drush hostmaster-install $_DOMAIN --aegir_host=$_AEGIR_HOST --aegir_db_user=$_USER --aegir_db_pass=$_AEGIR_DB_PASS --http_service_type=nginx --db_service_type=mysql --db_port=3306 --aegir_db_host=$_AEGIR_DB_HOST --client_email=$_ADM_EMAIL --script_user=$_USER --web_group=$_WEBG --profile=hostmaster -d -v"

drush hostmaster-install $_DOMAIN --aegir_host=$_AEGIR_HOST --aegir_db_user=$_USER --aegir_db_pass=$_AEGIR_DB_PASS --http_service_type=nginx --db_service_type=mysql --db_port=3306 --aegir_db_host=$_AEGIR_DB_HOST --client_email=$_ADM_EMAIL --script_user=$_USER --web_group=$_WEBG --profile=hostmaster -d -v

cd hostmaster-6.x-1.3
echo "alive" >> healthcheck

#enable aegir modules
drush @hostmaster en hosting_web_cluster
drush @hostmaster en hosting_alias
drush @hostmaster en hosting_http_basic_auth
#*** enable hosting client in features -- disabling client module cause WSOD on site add page

# setup aegirweb{1,2}
# test ssh to aegirweb{1,2}
# add to known_hosts

# NOTE: Aegir web clusters need to share the files, and private directories between web servers (also cache directory, if using boost module)
# Setup provision hook for NFS links
# http://drupal.org/node/1283738

mkdir -p /var/lib/sitedata/aegir
chown -R aegir:www-data /var/lib/sitedata/aegir

mkdir -p /var/lib/sitedata/aegir/cache
chown -R aegir:www-data /var/lib/sitedata/aegir/cache


# add web servers
# add web cluster
#TODO: Add DR web servers to cluster
#TODO: Add WR, re: DR web servers & firewall

# set date/time settings in Aegir

#TODO: Logrotate webserver logs

#TODO: Add an alias for the aegir user:
#aegir: "admin@domain.com""

========================

aegirweb{1,2}:
#TODO: Check puppeted stuff, fix, etc

sudo apt-get update
sudo apt-get upgrade

sudo mkdir -p /var/www/nginx-default

CATWEBDEBDEPS="mysql-client-5.1 vim nginx-custom drush postfix php5-cli php5-mysql php5-fpm php5-gd rsync unzip patch"
sudo apt-get -V install $CATWEBDEBDEPS


sudo adduser --system --group --home /var/aegir aegir
sudo adduser aegir www-data
sudo chsh -s /bin/bash aegir

#install SSL cert to:
/etc/ssl/private/domain.com.cert.pem
cd /etc/ssl/private/
ln -s domain.com.cert.pem nginx-wild-ssl.crt
ln -s domain.com.cert.pem nginx-wild-ssl.key

#install SSL config to:
/var/aegir/config/server_master/nginx/pre.d/nginx_wild_ssl.conf
#TODO: also install for /var/aegir/config/server_aegirweb{1,2}.host.name

#as root:
echo "aegir ALL=NOPASSWD: /etc/init.d/nginx" >> /etc/sudoers

#as aegir:
mkdir /var/aegir/.ssh
cat aegir.aegircontrol.id_rsa.pub >> /var/aegir/.ssh/authorized_keys2


#TODO: Logrotate webserver logs

==========================

Note: This installation process assumes that you're using a fresh install of Ubuntu 14.04 x64. If you use a lower version of Ubuntu, you may have trouble with this guide.

On most VPS providers, you'll be logged in as root initially. The installation process below assumes that you are logged in as root. Obviously, this is not a secure long-term solution, so once you're done with this guide, I suggest setting up public key authentication, turning off root login over SSH, and creating yourself a new unprivileged user. That's out of scope for this doc page, so you're probably on your own for that.

Finally, this document assumes that you're going to be installing aegir at aegir.example.com. Any time you see example.com, replace it with your domain.

1. Housekeeping

Make sure you're up to date:

apt-get update
apt-get upgrade

And that you have the the python-software-properties package (we'll need it later):

apt-get install python-software-properties

2. Install MariaDB

From mariadb.org:

MariaDB is a database server that offers drop-in replacement functionality for MySQL. 
MariaDB is built by some of the original authors of MySQL, with assistance from the
broader community of Free and open source software developers. In addition to the core
functionality of MySQL, MariaDB offers a rich set of feature enhancements including
alternate storage engines, server optimizations, and patches.

Install MariaDB:

apt-get install mariadb-server

You'll need to set your root password for the MariaDB server

3. Install Nginx

Next, install Nginx and PHP-FPM:

apt-get install nginx php5-cli php5-mysql php5-fpm php5-gd

Create the default docroot for Nginx as well:

mkdir -p /var/www/nginx-default

4. Install all the other stuff

apt-get install git-core git-doc vim drush postfix rsync unzip bzr patch curl

When prompted for Postfix configuration, select "Internet Site", then use "example.com" for the System mail name.

5. Create the Aegir user

Easy:

adduser --system --group --home /var/aegir aegir
adduser aegir www-data
chsh -s /bin/bash aegir

6. Misc Configuration

Make sure the Aegir user is allowed to restart Nginx:

echo "aegir ALL=NOPASSWD: /etc/init.d/nginx" >> /etc/sudoers

Symlink Aegir's nginx configuration into place:

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

Disable duplicated directives in /etc/nginx/nginx.conf (the Aegir config specifies these values as well - if you do not disable them in the main nginx.conf, nginx will fail to restart). You can just remove (or comment them out with a "#") the lines that start with the following

types_hash_max_size
tcp_nopush
error_log

Then, restart Nginx:

service nginx restart

7. Install Aegir

IMPORTANT Switch to the Aegir user now: IMPORTANT

su - aegir
cd ~/

Download the latest Provision release:

mkdir ~/.drush
cd ~/.drush
wget -c http://ftp.drupal.org/files/projects/provision-6.x-2.1.tar.gz
tar -zxf provision-6.x-2.1.tar.gz
rm provision-6.x-2.1.tar.gz

Start the Aegir install process:

cd ~/
drush hostmaster-install aegir.example.com \
--aegir_host="aegir.example.com" \
--http_service_type="nginx" \
--aegir_db_user="root" \
--aegir_db_pass="[YOUR ROOT DATABASE PASSWORD]" \
--db_service_type="mysql" \
--db_port=3306 \
--aegir_db_host="localhost" \
--client_email="[YOUR EMAIL ADDRESS]" \
--script_user="aegir" \
--web_group="www-data" \
--profile=hostmaster

8. Optional Improvements

drupal.org/project/hosting_queue_runner

drupal.org/project/provision_boost

There are a few things that can go wrong in the install.

1. Verify and install run everything through SSH

Since Aegir has multi-server support, it is possible that you have a misconfigured "FQDN" and that aegir then tries to connect to the local server as a remote server. To check if you have a misconfigured server, run the following commands:

resolveip `uname -n`

If the command returns your IP address, you are all set. If it returns an error you will need to edit your /etc/hosts file.

First line of this file looks like:

127.0.0.1  localhost

Simply add all domains you want to this line. e.g:

127.0.0.1  localhost aegir.example.com example.com

2. NameVirtualHost *:80 has no VirtualHosts

It does not hurt anything, but it can be annoying in your logs. This may disappear as soon as you define your first virtual site using Aegir. If it does not, you most likely have a second NameVirtualHost statement in your configuration someplace other than in the Aegir configurations.

If you are on a Debian system, that is usually a configuration fragment in /etc/apache2/ports.conf or in a fragment symbolically linked in /etc/apache2/sites-enabled and it is safe to comment out any NameVirtualHost statements you find there as this really is a large part of the job you have asked Aegir to do for you.

Once those are commented out, the message should disappear.

3. Making sure it works

Your new Aegir server will be installed with a single site named the way you specified in your install script. That's great, but you may have more paths to that same server.

When you try to browse to your server for the first time from a non-localhost browser you may get an addressing issue. If you do, make sure that you actually have the server defined in DNS and that the DNS server was reloaded. If it was reloaded and you use slave servers, make sure that the serial number in the zone file was incremented so that the slaves automatically reload.

If you already have multiple URLs in your DNS which resolve to the same Aegir, you should check them. For instance: if your DNS resolves both aegir.example.com and sitecontrol.example.com to your new Aegir server's IP, you need to make sure that both are accommodated. If they will both get the same physical hostmaster site, one should be set up as an alias to the other. If they are indeed going to be separate sites you will have to create a new site node with the other name as a virtual site.

4. Access by the server's physical IP address

Another "gotcha" that you may run into is http access using the actual IP itself. Remember that the IP is not picked up by the site vhost and will not match a ServerName or ServerAlias - so it gets picked up by the default vhost. This is just standard apache stuff, nothing Aegir or Drupal specific here, but quite the annoyance and a potential problem.

You can easily work around it by simply adding the IP as a Site Alias in the site node in either the Aegir site (or another site that you may have defined which you would prefer the IP to address).

You can tell if you have the IP problem by simply pointing your browser to the server by IP as http://999.999.999.999/ and seeing what comes up. If you get an install screen, you have the problem. You certainly do not want that install screen getting executed!

The good news is that fixing it is easy.

Simply log into Aegir, click on Sites, click on the site name that you want the IP to address, click on Edit and scroll down to Domain Aliases. Put the IP into the box, click on the Redirect checkbox so that Aegir instructs Apache to do a rewrite to the real domain name, and finally click Save.

If you do not have the Domain Aliases entry box, you need to turn that feature on. In that case, go to your administration menu at the top of the page, point to Hosting and then click on Features. Click the checkbox for Site Aliasing and then Save Configuration. The Aliases box will now appear when you edit a site. There is excellent information about the site alias feature in this handbook at http://community.aegirproject.org/node/60 with much more detail.

After the Verify job completes you should test your server again. Now when you address the server by it's IP address the URL should automatically change to the site you selected and the install screen never appears.

5. CentOS firewall settings

You may need to adjust CentOS's firewall settings to allow HTTP traffic on port 80. If you installed CentOS with a UI, enable "Firewall settings -- WWW (HTTP)".

Alternatively, another solution may be to edit /etc/sysconfig/iptables and add a rule accepting traffic on the relevant interface on port 80.

Afterwards, you can restart the firewall with this command:

Shell commands::

6. CentOS cron requires restart?!

Also, in some configurations, it seems necessary to restart crond for the user crontab changes to take effect (very bizarre). For that, use:

Shell commands::

See http://drupal.org/node/632308 if you have more information about this issue.

7. CentOS aegir.conf permission denied

If you receive:

when trying to restart httpd, check your SELinux settings. If enabled, you can run the following command on the aegir.conf file in /var/aegir/config/server_master directory: Alternatively, you can disable SELinux completely if you desire. Both options will result in removing the permisson denied error.

You can see this comment: http://drupal.org/node/1286926#comment-5028062 for a little more info.

Try the following if nothing works:

setenforce permissive

See this doc to make the change permanent: http://wiki.centos.org/HowTos/SELinux

8. Solaris cron issues

I had numerous problems setting up a proper cron job, as Solaris' crond seems pretty anal about what it accepts. The only way I could get it to work was to create a wrapper shell script that would be called using the simplest cron tab.

Crontab entry:

Content of dispatch.sh:

9. Drush execution path issues

Solaris (and maybe others) suffers from the dreaded execution issues of drush:

• http://drupal.org/node/637574
• http://drupal.org/node/586466

Those can be worked around by hardcoding the --php executable on the commandline path. Adding the proper shebang (#!/usr/local/bin/php, for example) header and using a proper PATH that includes the PHP executable also helps.

10. APC issues

If you are having trouble running APC with Aegir, try downgrading to APC 3.1.4. This can be achieved by the following:

sudo pecl uninstall apc

sudo pecl install apc-3.1.4

As explained at http://community.aegirproject.org/installing/manual, the recommended version of PHP is 5.3, but some users may wish to use PHP 5.2 in order to host Drupal 5.x sites or to use modules which have PHP 5.3 compatibility issues. Should you choose to do so, the following documentation may be useful. What is explained here is specific to Ubuntu 10.04. It hasn't been tested on further versions, mostly because many sysadmins prefer to use the latest Long Term Support (LTS) version of Ubuntu, currently 10.04, on their production servers.

Follow this procedure :

sudo apt-get install python-software-properties

add-apt-repository ppa:txwikinger/php5.2

Create the file /etc/apt/preferences.d/php and input the following code in it :

Package: libapache2-mod-php5
Pin: version 5.2.10*
Pin-Priority: 991

Package: libapache2-mod-php5filter
Pin: version 5.2.10*
Pin-Priority: 991

Package: php-pear
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-cgi
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-cli
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-common
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-curl
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-dbg
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-dev
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-gd
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-gmp
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-ldap
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-mhash
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-mysql
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-odbc
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-pgsql
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-pspell
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-recode
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-snmp
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-sqlite
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-sybase
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-tidy
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-xmlrpc
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-xsl
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-mcrypt
Pin: version 5.2.6*
Pin-Priority: 991

Package: php5-imap
Pin: version 5.2.6*
Pin-Priority: 991

Then proceed Aegir install as explained at http://community.aegirproject.org/installing/debian