INSTALL.txt in Hostmaster (Aegir) 5.x

-*-rst-*-

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

This document is formatted using the ReST syntax.

Aegir 0.2 requirements
======================

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

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.

That webserver should probably 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.

Shell commands::
 apt-get install apache2

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.

Shell commands::
 apt-get install php5 php5-cli php5-mysql

MySQL server
------------

You will require a MySQL server, obviously. It is preferable to use a
dedicated server since Aegir will create MySQL users, since it will
require a "root" MySQL user.

Mail transfer agent
-------------------

Aegir requires an MTA (Mail Transfer Agent) installed on your
webserver in order to be able to install a new site to your new
platform. If you don't have an MTA you 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.  On Debian-based systems do:

Shell commands::
 sudo apt-get install postfix
    
Once that is done you should be able to install a site to the new platform. 

Aegir 0.2 installation instructions
===================================

This section deals with the installation of Aegir proper. Those
instructions limit themselves to getting you into the Aegir wizard,
which will then give you further configuration instructions.

This document assumes the Aegir home is in /var/aegir, adapt as desired,
but make sure that the user you create (as suggested in the install
wizard) has this directory configured as its home directory.

Checking out the code
---------------------

This assumes you have installed CVS. Those commands should be ran as the
aegir user and assume it can write to /var/aegir.

Shell commands::
 export CVSROOT=:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal
 cd /var/aegir
 cvs co -d drupal-5.x -r DRUPAL-5-18 drupal
 cd drupal-5.x
 cvs co -d profiles/hostmaster -rDRUPAL-5--0-2 contributions/profiles/hostmaster
 cvs co -d profiles/hostmaster/modules/hosting -rDRUPAL-5--0-2 contributions/modules/hosting
 cd /var/aegir
 cvs co -d drush -rDRUPAL-6--2-0 contributions/modules/drush
 mkdir .drush
 cvs co -d .drush/provision -rDRUPAL-6--0-2 contributions/modules/provision

Checking out the optional components
------------------------------------

Aegir now has its own theme which you can use. It is also suggested
that you install admin_menu to ease administration.

Note that now your drush installation should be up and running so you
can start using it to download modules directly. This is how
admin_menu is installed below. The theme is installed using CVS
because the release may not yet be available when you read this
document.

This is optional.

Shell commands::
 cvs co -d drupal-5.x/profiles/hostmaster/themes/eldir -rDRUPAL-5--0-2 contributions/themes/eldir
 cd drupal-5.x ; /var/aegir/drush/drush.php dl admin_menu

Apache configuration
--------------------

Those instructions assume you are running Debian specific and
installing aegir in http://aegir.example.com. If you are running
another system you basically need to:

 1. create a directory for Aegir configs
 2. activate the mod_rewrite engine
 3. include the Aegir apache configurations in Apache
 4. create a base configuration file for Aegir in /var/aegir/config/vhost.d/aegir.example.com
 5. restart apache

So this needs to be ran as root too.

Shell commands::
 cd /var/aegir
 mkdir -p config/vhost.d/
 a2enmod rewrite
 echo "Include /var/aegir/config/vhost.d/" > /etc/apache2/conf.d/aegir
 cp drupal-5.x/profiles/hostmaster/apache2.conf.txt config/vhost.d/aegir.example.com
 /etc/init.d/apache2 restart

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

Here you want to make a basic database configuration for the Drupal
you are going to install. You want to run those commands using your
database 'root' user.

SQL commands::
 CREATE DATABASE aegir;
 GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, \
  CREATE TEMPORARY TABLES, LOCK TABLES ON aegir.* TO \
  'aegir'@'localhost' IDENTIFIED BY 'XXXXXXXX';

Install the Drupal
------------------

Now you are ready to install the first Drupal using this installation
profile. Point your browser to http://aegir.example.com/ , assuming
DNS is properly configured to point to your webserver, otherwise you
may want to try http://localhost/ .

The installer is going to complain about the permissions of
settings.php, just fix the permissions:

Shell commands::
 chmod a+w /var/aegir/drupal-5.x/sites/default/settings.php

Select the hostmaster install profile, enter the database credentials
you setup above and then the installer will prompt you to secure the
permissions on the settings.php file again:

Shell commands::
 chmod a-w /var/aegir/drupal-5.x/sites/default/settings.php

Follow the wizard
-----------------

You should now be in the installation wizard. The wizard is usually
self-documenting so you should just be able to follow the instructions
in the wizard to configure Aegir to properly use the webserver and
database server.

Installing new platforms
------------------------

To deploy new platforms to provisions site to, you simply need to
download the platform source code (which can be done with drush) and
then, on the hostmaster site, create a new Platform node which points
to where the source was downloaded.

Shell commands::
 cd /var/aegir
 ./drush/drush.php dl drupal

Use "drush dl drupal-5.x" to get the latest release of the 5.x branch.