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'

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
+
+# $Id$
+
+########################################################################
+# Aegir quick install script
+#
+# This script takes care of deploying all the required PHP scripts for
+# the frontend to run properly. It should be ran as the Aegir user.
+#
+# It should keep to strict POSIX shell syntax to ensure maximum
+# portability. The aim here is to ease the burden on porters but also
+# allow people using various platforms to zip through the install quicker.
+#
+# Eventually, all this should be performed by the Provision backend.
+#
+# This script also *DOES NOT CHECK* if the requirements have been met.
+# It's up to the admin to follow the proper install instructions or use
+# the packages provided by their platform.
+
+########################################################################
+# basic variables, change before release
+AEGIR_DOMAIN=aegir.example.com 
+AEGIR_VERSION=HEAD
+AEGIR_HOME=$HOME
+WEB_GROUP=www-data
+DRUSH_VERSION=6.x-3.0-alpha1
+DRUSH_MAKE_VERSION=6.x-2.0-beta6
+
+# when adding a variable here, add it to the display below
+
+########################################################################
+# functions
+
+# noticeable messages
+msg() {
+  echo "==> $*"
+}
+
+# simple prompt
+prompt_yes_no() {
+  while true ; do
+    printf "$* [Y/n] "
+    read answer
+    if [ -z "$answer" ] ; then
+      return 0
+    fi
+    case $answer in
+      [Yy]|[Yy][Ee][Ss])
+        return 0
+        ;;
+      [Nn]|[Nn][Oo])
+        return 1
+        ;;
+      *)
+        echo "Please answer yes or no"
+        ;;
+    esac
+ done 
+
+}
+
+usage() {
+  cat <<EOF
+Usage: $0 [ -V version ] [ -h ] [ -w group ] [ -d home ] hostname
+EOF
+}
+
+########################################################################
+# Main script
+
+# stop on error
+set -e
+
+# parse commandline
+args=`getopt V:w:d:h $*`
+set -- $args
+
+for i
+do
+  case "$i" in
+    -w) shift; WEB_GROUP=$1; shift;;
+    -h) shift; usage; exit;;
+    -V) shift; AEGIR_VERSION=$1; shift;;
+    -d) shift; AEGIR_HOME=$1; shift;;
+    --) shift; break;;
+  esac
+done
+
+AEGIR_DOMAIN=${1:-$AEGIR_DOMAIN}
+DRUSH="$AEGIR_HOME/drush/drush.php"
+HOSTMASTER_DIR=$AEGIR_HOME/hostmaster-$AEGIR_VERSION
+
+msg "Aegir automated install script"
+
+if [ `whoami` = "root" ] ; then
+  msg "This script should be ran as a non-root user"
+  exit 1
+fi
+
+msg "This script makes the following assumptions: "
+cat <<EOF
+ * you have read INSTALL.txt and prepared the platform accordingly
+ * you are running as your "aegir" user
+ * the following settings are correct:
+AEGIR_DOMAIN=$AEGIR_DOMAIN
+AEGIR_VERSION=$AEGIR_VERSION
+AEGIR_HOME=$AEGIR_HOME
+WEB_GROUP=$WEB_GROUP
+HOSTMASTER_DIR=$HOSTMASTER_DIR
+DRUSH=$DRUSH
+DRUSH_VERSION=$DRUSH_VERSION
+
+Some of those settings can be changed on the commandline, see:
+
+ $0 -h
+
+for more information.
+EOF
+
+if prompt_yes_no "Do you want to proceed with the install?" ; then
+  true
+else
+  echo "installation aborted by user"
+  exit 1
+fi
+
+msg "Creating basic directory structure"
+mkdir -p $AEGIR_HOME/config/vhost.d
+mkdir -p $AEGIR_HOME/backups
+chmod 0711 $AEGIR_HOME/config
+chmod 0700 $AEGIR_HOME/backups
+
+# we need to check both because some platforms (like SunOS) return 0 even if the binary is not found
+if which drush 2> /dev/null && which drush | grep -v 'no drush in' > /dev/null; then
+  msg "Drush is in the path, good"
+  DRUSH=drush
+elif [ -x $DRUSH ] ; then
+  msg "Drush found in $DRUSH, good"
+  DRUSH="php $AEGIR_HOME/drush/drush.php"
+else
+  msg "Installing drush in $AEGIR_HOME"
+  cd $AEGIR_HOME
+  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
+  DRUSH="php $AEGIR_HOME/drush/drush.php"
+fi
+
+if $DRUSH help > /dev/null ; then
+  msg "Drush seems to be functionning properly"
+else
+  msg "Drush is broken ($DRUSH help failed)"
+  exit 1
+fi
+
+if $DRUSH help | grep "^ make" > /dev/null ; then
+  msg "Drush make already seems to be installed"
+else
+  msg "Installing drush make in $AEGIR_HOME/.drush"
+  mkdir -p $AEGIR_HOME/.drush
+  $DRUSH dl drush_make-$DRUSH_MAKE_VERSION --destination=$AEGIR_HOME/.drush
+fi
+
+if $DRUSH help | grep "^ provision install" > /dev/null ; then
+  msg "Provision already seems to be installed"
+else
+  msg "Installing provision backend in $AEGIR_HOME/.drush"
+  mkdir -p $AEGIR_HOME/.drush
+  if [ "$AEGIR_VERSION" = "HEAD" ]; then
+    git clone git://git.aegirproject.org/provision $AEGIR_HOME/.drush/provision
+  else
+    cd $AEGIR_HOME/.drush
+    wget http://files.aegirproject.org/provision-$AEGIR_VERSION.tgz
+    gunzip -c provision-$AEGIR_VERSION.tgz | tar -xf -
+    rm provision-$AEGIR_VERSION.tgz
+  fi
+fi
+
+if [ ! -d $HOSTMASTER_DIR ] ; then
+  msg "Deploying hostmaster application"
+  $DRUSH hostmaster-make $HOSTMASTER_DIR
+  cd $HOSTMASTER_DIR
+  mkdir sites/$AEGIR_DOMAIN
+  cp sites/default/default.settings.php sites/$AEGIR_DOMAIN/settings.php
+  chmod g+w sites/$AEGIR_DOMAIN/settings.php
+  mkdir sites/$AEGIR_DOMAIN/files
+  chmod 2770 sites/$AEGIR_DOMAIN/files
+  chgrp $WEB_GROUP sites/$AEGIR_DOMAIN/settings.php
+  chgrp $WEB_GROUP sites/$AEGIR_DOMAIN/files
+fi
+
+if [ ! -f $AEGIR_HOME/config/vhost.d/$AEGIR_DOMAIN ]; then
+  sed -e "s#DocumentRoot .*#DocumentRoot $HOSTMASTER_DIR#" -e "s#Directory .*#Directory $HOSTMASTER_DIR>#" -e "s/ServerName .*/ServerName $AEGIR_DOMAIN/" $HOSTMASTER_DIR/profiles/hostmaster/apache2.conf.txt > $AEGIR_HOME/config/vhost.d/$AEGIR_DOMAIN
+  msg "Installed apache configuration file for $AEGIR_DOMAIN, you will need to restart apache"
+fi
+
+msg "Install process complete: follow the wizard"
+
+cat <<EOF
+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.
+EOF