move install instructions to provision to simplify the bootstrap process (we...

move install instructions to provision to simplify the bootstrap process (we just need provision now

HINTS_CentOS.txt

+.. This document is formatted using the ReST syntax.
+
+===============================================
+Aegir -- CentOS installation instructions hints
+===============================================
+
+This is a helper file to the canonical INSTALL.txt. It is aimed at
+helping you install Aegir on CentOS. It simply lists commands that
+diverge from the base INSTALL.txt in a concise document that will be
+easy to maintain in the long term.
+
+It is recommended that the INSTALL.txt document is consulted before
+going ahead with this install.
+
+We reuse the same process describe in that document:
+
+ 1. Install requirements
+ 2. Configure system requirements, which include:
+    * create a Aegir user
+    * configure Apache, MySQL, DNS, etc
+ 3. Install the Aegir files
+ 4. Follow the install wizard
+
+
+1. Install software requirements
+================================
+
+You should use the repos "utter ramblings" repos (which feature PHP
+5.2) at: http://www.jasonlitka.com/yum-repository/
+
+Shell commands::
+
+ rpm --import http://www.jasonlitka.com/media/RPM-GPG-KEY-jlitka
+ cat >> /etc/yum.repos.d/utterramblings.repo <<EOF
+[utterramblings]
+name=Jason's Utter Ramblings Repo
+baseurl=http://www.jasonlitka.com/media/EL\$releasever/\$basearch/
+enabled=1
+gpgcheck=1
+gpgkey=http://www.jasonlitka.com/media/RPM-GPG-KEY-jlitka
+EOF
+ yum install httpd postfix cvs sudo unzip mysql-server php php-mysql
+
+2. Configure system requirements
+================================
+
+Shell commands::
+ useradd --home-dir /var/aegir aegir
+ gpasswd -a aegir www-data
+ chmod -R 755 /var/aegir
+ # Include the Aegir config
+ echo "Include /var/aegir/config/vhost.d/" > /etc/httpd/conf.d/aegir.conf
+ service mysqld start
+ # Optional: set the mysql root password
+ mysqladmin password $password
+ mysql -uroot -p
+
+The last two lines can also be (better) accomplished using the
+mysql_secure_installation script.
+
+MySQL commands::
+ # Replace 'aegir_password' with the chosen password for 'aegir' mysql account
+ CREATE DATABASE aegir;
+ GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, \
+   CREATE TEMPORARY TABLES, LOCK TABLES ON aegir.* TO \
+   'aegir'@'localhost' IDENTIFIED BY 'aegir_password';
+ # Create a mysql super user (with GRANT OPTION)
+ # Replace 'aegir_root_password' with a new password
+ GRANT ALL PRIVILEGES ON *.* TO 'aegir_root'@'localhost' \
+   IDENTIFIED BY 'aegir_root_password' WITH GRANT OPTION;
+
+You may need to edit your local hosts file to get the aegir domain to work if you 
+have not already added a DNS record for this. On OS X:
+
+http://decoding.wordpress.com/2009/04/06/how-to-edit-the-hosts-file-in-mac-os-x-leopard/
+
+
+3. Install the Aegir files
+==========================
+
+Shell commands::
+ su aegir -c "sh install.sh.txt -w apache"
+ service httpd restart
+
+
+4. Follow the install 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.
+
+5. Common issues
+================
+
+There are various caveats on running Aegir on CentOS.
+
+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)".
+
+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::
+ service crond restart
+
+See http://drupal.org/node/632308 if you have more information about
+this issue.
+
+The default sudo configuration in CentOS requires sudo to run in a real
+TTY which will make verify and install tasks failed with the message:
+
+ "Web server could not be restarted. Changes might not be available
+ until this has been done"
+
+For sudo to behave properly, you should comment out the following line
+in your /etc/sudoers file:
+
+Defaults    requiretty

HINTS_Solaris.txt

+.. This document is formatted using the ReST syntax.
+
+================================================
+Aegir -- Solaris installation instructions hints
+================================================
+
+This is a helper file to the canonical INSTALL.txt. It is aimed at
+helping you install Aegir on Solaris. It simply lists commands that
+diverge from the base INSTALL.txt in a concise document that will be
+easy to maintain in the long term.
+
+It is recommended that the INSTALL.txt document is consulted before
+going ahead with this install.
+
+We reuse the same process describe in that document:
+
+ 1. Install requirements
+ 2. Configure system requirements, which include:
+    * create a Aegir user
+    * configure Apache, MySQL, DNS, etc
+ 3. Install the Aegir files
+ 4. Follow the install wizard
+
+1. Install software requirements
+================================
+
+TODO: Show how to install:
+
+ * Apache2
+ * git
+ * sudo
+ * mysql
+ * PHP 5.2
+ * wget
+
+unzip and sendmail should be part of the base Solaris install. Other
+applications should be available on the companion CDs or:
+
+http://www.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
+plainly.
+
+XXX: 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. Configure system requirements
+================================
+
+Shell commands::
+ groupadd aegir
+ useradd -g aegir -G webservd -d /var/aegir -s /bin/bash -c "Aegir sandbox" aegir
+ chown aegir:aegir /var/aegir
+ echo "Include /var/aegir/config/vhost.d/" >> /etc/apache2/httpd.conf
+
+MySQL commands::
+ # Replace 'aegir_password' with the chosen password for 'aegir' mysql account
+ CREATE DATABASE aegir;
+ GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, \
+   CREATE TEMPORARY TABLES, LOCK TABLES ON aegir.* TO \
+   'aegir'@'localhost' IDENTIFIED BY 'aegir_password';
+ # Create a mysql super user (with GRANT OPTION)
+ # Replace 'aegir_root_password' with a new password
+ GRANT USAGE,CREATE USER ON *.* TO 'aegir_root'@'localhost' \
+   IDENTIFIED BY 'aegir_root_password' WITH GRANT OPTION;
+ GRANT ALL PRIVILEGES ON `site\_%`.* TO 'aegir_root'@'localhost';
+
+3. Install the Aegir files
+==========================
+
+Shell commands::
+ su - aegir
+ bash install.sh.txt -w webservd -d /var/aegir
+
+4. Follow the install 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.
+
+5. Common issues
+================
+
+Drush issue
+-----------
+
+Solaris 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 header and using a proper
+PATH that includes the PHP executable also helps.
+
+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::
+
+ * * * * * /var/aegir/dispatch.sh
+
+Content of dispatch.sh::
+ #!/usr/bin/bash
+ 
+ HOME=/var/aegir
+ LD_LIBRARY_PATH=/usr/lib:/usr/local/lib:/usr/lib/sparcv9:/opt/mysql/mysql/lib:/usr/sfw/lib:/usr/sfw/lib/gcc:/opt/sfw/lib
+ PATH=/usr/bin:/opt/mysql/mysql/bin:/usr/sfw/bin:/opt/sfw/bin:/opt/SUNWspro/bin:/usr/local/bin:/opt/csw/bin
+ 
+ export HOME
+ export LD_LIBRARY_PATH
+ export PATH
+ 
+ php '/var/aegir/drush/drush.php' --php=/usr/local/bin/php hosting tasks --root='/var/aegir/hostmaster-HEAD' --uri='http://aegir.example.com'

INSTALL.txt

+.. 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 4 basic steps:
+
+ 1. Install requirements
+ 2. Configure system requirements, which include:
+    * create a Aegir user
+    * configure Apache, MySQL, DNS, etc
+ 3. Install the Aegir files
+ 4. Follow the install wizard
+
+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.
+
+
+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.
+
+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.
+
+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.
+
+More detailed instructions on this topic will be given later in the web 
+installation wizard.
+
+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
+--------------------
+
+The rewrite module must be enabled and also Apache must be given a
+directive to include Aegir's vhosts path, to read configurations from
+there.  In Debian-based systems you can put a file inside
+``/etc/apache2/conf.d`` that will be parsed on startup or
+alternatively you can place the directive in 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.
+
+Shell commands as root::
+
+ a2enmod rewrite
+ echo "Include /var/aegir/config/vhost.d/" > /etc/apache2/conf.d/aegir
+
+
+Database configuration
+----------------------
+
+Here you want to make a basic database configuration for the Drupal site
+you are going to install. You want to run these commands using your
+mysql 'root' user, substituting the 'XXXXXXXX' with a real password.
+
+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';
+
+
+DNS Configuration
+-----------------
+
+Configuring DNS is up to you. Currently Aegir does nothing with DNS. 
+
+As a help trick, if you are installing Aegir locally to try and test it,
+you can do local DNS by adding entries to file ``/etc/hosts``. First
+line of this file looks like:
+
+``127.0.0.1  localhost your-machine-name``
+
+Simply add all domains you want to this line. e.g:
+
+``127.0.0.1  localhost your-machine-name $AEGIR_DOMAIN other1 other2``
+
+3. Install the Aegir files
+==========================
+
+This section deals with the installation of Aegir proper. These
+instructions limit themselves to getting you into the Aegir install wizard,
+which will then give you further configuration instructions.
+
+There is an install script part of the hostmaster profile that takes care
+of installing the right packages and preparing the Drupal frontend install
+for you. That script needs to be run as the aegir user created above.
+This file is available alongside this one or can be downloaded through the 
+web at:
+
+http://git.aegirproject.org/?p=hostmaster.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.
+
+The install script is shipped with other default settings that you 
+will likely need to change (such as the URL of the Aegir site) prior 
+to running it.
+
+You can change which release to install or other parameters such as these
+through options passed to the script. Run "sh
+install.sh.txt -h" for more information on the available options.
+
+Shell commands::
+
+ su -s /bin/sh aegir -c "sh install.sh.txt"
+ /etc/init.d/apache2 restart
+
+Note you must run this as root or prefix with sudo.
+
+Checkpoint!
+-----------
+
+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. 
+
+
+4. Follow the install wizard
+============================
+
+Now point your browser to http://$AEGIR_DOMAIN/install.php and proceed
+with the remainder of the installation using the Hostmaster Install
+profile.  Some of the instructions given, you will already have
+completed, but carefully read each step in turn to ensure you don't miss
+anything.  Specifically you must still provide the database credentials,
+add the Aegir user to /etc/sudoers with the relevant command to restart
+the webserver, create a MySQL superuser capable of creating more databases, 
+and initialise the hosting system.  These instructions are provided to you
+by the Hostmaster install profile.

UPGRADE.txt

+.. This document is formatted using the ReST syntax.
+
+==========================
+Aegir Upgrade Instructions
+==========================
+
+-----------------------------------------------------------------------------
+This document describes briefly how to upgrade an existing Aegir installation
+-----------------------------------------------------------------------------
+
+Conventions and tips
+====================
+
+All instructions and in general all commands must be run as aegir user,
+so all permissions are always set correctly.
+
+To become aegir user you can issue this command::
+
+  su -s /bin/sh aegir
+
+(Note you must run this as root or prefix with sudo).
+
+Note that /bin/sh is an example. You may wish to instead use the shell
+of your choice, i.e /bin/bash
+
+Additionally to make following instructions generic and not dependant on
+a concrete Drupal or Aegir version, we will use shell environment
+variables. Since 0.4, the hostmaster platform is prepended with 'hostmaster'
+so as not to clash with any other Drupal platforms. If you are upgrading from
+Aegir version 0.3, your hostmaster platform may be called 'drupal-6.14'.
+
+You should replace the following variables for current versions at the time
+you are reading this document.
+
+Shell commands::
+
+  export AEGIR_VERSION=HEAD
+  export DRUPAL_DIR=/var/aegir/hostmaster-$AEGIR_TAG
+  export OLD_DRUPAL_DIR=/var/aegir/drupal-6.14
+  export DRUSH_VERSION=6.x-3.0-alpha1.tar.gz
+  export DRUSH_MAKE_VERSION=6.x-2.0-beta6
+
+This document also assumes drush is installed properly and we use an
+environment variable to simplify the documentation again.
+
+Shell commands::
+
+  export DRUSH='php /var/aegir/drush/drush.php'
+
+As of the 0.4-alpha3 release, 'unzip' is a required dependency on your 
+server in order to successfully extract the jquery.ui library that is
+part of some UI improvements. On Debian, this means:
+
+Shell commands::
+
+ apt-get install unzip
+
+If you intend on upgrading your system to the bleeding edge version of the
+code from our git repositories, you will need the git program installed.
+On Debian, this means:
+
+Shell commands::
+
+ apt-get install git-core
+
+Generic upgrade instructions
+============================
+
+We aim to create a generic upgrade process that will be consistent
+across versions. This section describes this process. However, there
+are version-specific upgrade instructions that may be more relevant to
+your installation in the next section.
+
+Upgrading the backend
+---------------------
+
+In general, we try to keep the backend and the frontend compatible
+with each other during release cycles. That is: provision 0.3 and
+hosting 0.3 will always be able to talk to each other. hosting 0.2 was
+able to talk to provision 0.3 too, but the API is not well enough
+defined so that can be counted upon.
+
+Therefore, you want to keep the frontend and the backend in sync. When
+you do a major upgrade (e.g. 0.3 -> 0.4) of the backend, you *must*
+upgrade the frontend soon after.
+
+Bottomline: first you upgrade the backend, then the frontend.
+
+Upgrading the backend is as simple as installing a new version of
+Drush and Provision over the old ones.
+
+Keep a copy of the old Provision and Drush in case something goes wrong 
+in the frontend.
+
+Shell commands::
+
+  cd /var/aegir
+  mv drush drush.bak
+  wget http://ftp.drupal.org/files/projects/drush-$DRUSH_VERSION.tar.gz 
+  gunzip -c drush-$DRUSH_VERSION.tar.gz | tar -xf -
+  rm drush-$DRUSH_VERSION.tar.gz
+  cd /var/aegir/.drush
+  mv provision ../provision.bak
+  wget http://files.aegirproject.org/provision-$AEGIR_VERSION.tgz
+  gunzip -c provision-$AEGIR_VERSION.tgz | tar -xf -
+  rm provision-$AEGIR_VERSION.tgz
+
+Provision 0.4 has added a new dependency on drush_make, which will also
+need to be installed to upgrade the front end if you are upgrading from
+a pre-0.4 release.
+
+If you are upgrading from an earlier 0.4 release, replace your copy of
+drush_make with the latest recommended release.
+
+Shell commands::
+
+  $DRUSH dl drush_make-$DRUSH_MAKE_VERSION --destination='/var/aegir/.drush'
+
+Upgrading the frontend
+----------------------
+
+These are generic instructions to upgrade your hosting, hostmaster,
+eldir or Drupal core installation to new versions. As of 0.4 this process
+has largely been automated, and will be able to upgrade 0.3 and any of
+the 0.4 development releases to the latest applicable versions.
+
+Once you have upgraded the backend, and you have installed drush_make
+you will need to run the hostmaster migrate command.
+
+
+Shell commands::
+
+  cd $OLD_DRUPAL_DIR
+  $DRUSH hostmaster-migrate aegir.example.com $DRUPAL_DIR
+
+The directory specified must be an absolute path to where you want
+the new release to be stored. If the directory does not exist, provision
+will use drush_make to fetch and assemble the correct version of the front
+end for the specific release of the backend you are running.
+
+This command will completely replace the crontab entry for the aegir user,
+and asks for confirmation before it does so. If you do not confirm, the process
+will be halted as it is necessary for the task queue to be processed.
+
+The command above will fetch the latest stable Drupal release, so it can simply
+be run again when a new security release of Drupal is made available.
+

install.sh.txt

+#! /bin/sh
+
+