INSTALL.txt

.. -*- mode: rst; fill-column: 78; -*-
.. This document is formatted using the ReST syntax.

=================================
 Aegir Installation Instructions
=================================

------------------------------------------------------------------------------
This document describes briefly how to install a multi-platform, single-server
Aegir Drupal provisionning system.
------------------------------------------------------------------------------

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

 1. Install requirements
 2. Configure system requirements, which include:
    * create a Aegir user
    * configure Apache, MySQL, DNS, etc
 3. Run the install script.

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

Platform-specific cheat sheets are also available for other platforms in
HINTS_*.txt files alongside this document. Those files are basically a
bullet-point summary of the steps required for the installation. In case of
conflict between INSTALL.txt and other documentation, INSTALL.txt should be
considered the canonical source of information.

Also note that those instructions setup a complete Aegir system. If you want
to only setup a new server, it should be sufficient to install requirement
(step 1) and configure them (step 2). You will just need the -b flag to
avoid installing the frontend on the server.

1. Install software requirements
================================

This section describes what is expected of the servers Aegir is running on.

Aegir must run some UNIX flavour 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.

The level of access required to be able to configure this system is very far
beyond what is commonly available to users with shared hosting.  Commands are
assumed to be run as root user.

Web server
----------

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

PHP 5.2
-------

Since Aegir strongly depends on Drush, we therefore depend on PHP 5.2 or
above. You also need to have the commandline version of PHP to run Drush
properly and the MySQL extensions.

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

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

Database server
---------------

You will require a database server, obviously. Aegir currently only supports
MySQL. It is preferable to use a dedicated server since Aegir will create
database users and will require a privileged 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, git and unzip
------------------------------

Aegir installs itself via a drush_make file 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.

Summary
-------

This may vary according to your platform, but under a Debian derivative, you
can install all those packages using the following.

Shell commands::

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


2. Configure system requirements
================================

The following details what configuration needs to be performed on the server
before going ahead with the install.


DNS Configuration
-----------------

Aegir requires that the hostname returned by the `hostname` and `uname -n`
shell commands, resolves to the IP address for this server.

Shell commands as root::
  AEGIR_HOST=`uname -n`
  resolveip $AEGIR_HOST

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_HOST $AEGIR_DOMAIN other1 other2``

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.

Aegir user
----------

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

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

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

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

Shell commands::

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


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.

Shell commands as root::

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

The aegir user needs to have sudo access. Add the relevant line to your sudoers
file.

/etc/sudoers configuration::
  aegir ALL=NOPASSWD: /usr/sbin/apache2ctl

Remote web servers
------------------

Any number of remote web servers may be configured. They need an aegir user and
Apache configuration as above, with the same user name and directory paths. SSH
public/private keys should be set up so hostmaster's Aegir user can access
remote web Aegir users with no passwords.

They will also need a login shell, which can be modified using the `chsh` command.

Shell command as root::
  chsh -s /bin/sh aegir

Database configuration
----------------------

To make sure that the Aegir backend, and all the possible web servers can
reach your database server, you need to configure mysql to listen on all
the public IP addresses available to it.

/etc/mysql/my.cnf configuration line to comment out::
  bind-address	= 127.0.0.1

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. It will
not store this information, but instead use it to generate a new super
user account for the aegir system.

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.

3. Run the install script
=========================

This section deals with the actual installation of Aegir.

There is an install script that takes care of installing the right packages and 
preparing the backend and frontend install for you. That script needs to be run 
as the aegir user created above.  This file is available in Provision or can be 
downloaded through the web at:

http://git.aegirproject.org/?p=provision.git;a=blob_plain;f=install.sh.txt;hb=HEAD

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

Shell commands::
 su -s /bin/sh aegir -c "sh install.sh.txt aegir.example.com"

Note you must run this as root or prefix with sudo.

Be sure to change 'aegir.example.com' to match the URI of your site.

You can append '--client_email=you@example.com' if you wish to receive the 
traditional Drupal 'Welcome' e-mail upon completion of the installation.
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.

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-0.x/
 /var/aegir/hostmaster-0.x/profiles/hostmaster/
 /var/aegir/hostmaster-0.x/profiles/hostmaster/modules/admin_menu/
 /var/aegir/hostmaster-0.x/profiles/hostmaster/modules/hosting/
 /var/aegir/hostmaster-0.x/profiles/hostmaster/modules/install_profile_api/
 /var/aegir/hostmaster-0.x/profiles/hostmaster/modules/jquery_ui/
 /var/aegir/hostmaster-0.x/profiles/hostmaster/modules/modalframe/
 /var/aegir/hostmaster-0.x/profiles/hostmaster/themes/eldir/
 /var/aegir/hostmaster-0.x/sites/aegir.example.com/
 /var/aegir/config/vhost.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.